helical___abortDatasetUpload
ChatGPTCancels a multipart upload started by initiateDatasetUpload and deletes the parts already uploaded. Call this whenever you give up on an upload — a failed part, an expired URL, or a size mismatch you intend to redo. Uploaded parts otherwise linger and are billed as storage. Safe to repeat: an upload that is already gone is reported as success, so a retry after a timeout or an unclear outcome costs nothing. A 502 means the abort did not happen and the parts are still stored — retry it, and if it keeps failing say so rather than assuming the upload was cleaned up. Does NOT delete an already-completed object, and does not touch registered datasets. 404 if the key is not your own staging object.
helical___completeDatasetUpload
ChatGPTStep 2 of 3: call this once every part from initiateDatasetUpload has been PUT successfully. The server reads the uploaded parts and their ETags from S3 itself, so send no part list. The assembled object is whatever parts arrived, so do not call this while a part's PUT is still outstanding or has failed. Fails with 400 if no parts arrived or if part numbers are not contiguous from 1 — re-upload the missing part and call this again. 404 if the key is not your own staging object. On success, call registerDataset with the returned s3Key to create the catalogue row.
helical___deleteDataset
ChatGPTQueues the deletion of a dataset the user uploaded. Nothing changes until resolveConfirmation approves the returned confirmation_id. Spends no credit. Once approved, the dataset no longer appears in listDatasets or getDataset and cannot be used for new runs. The stored file is not removed. Past runs that used it, and their charges, are unaffected. 404 if the dataset doesn't exist, is already deleted, or was not uploaded by this user. 403 if the user has read-only access. 409 if a deletion of this dataset is already queued — recover its confirmation_id with listPendingConfirmations.
helical___downloadArtifact
ChatGPTReturns a presigned GET URL for a single artifact produced by one of your runs — an embedding matrix, a UMAP, a perturbation AnnData. Fetch it with curl -o '<fileName>' '<url>'; no auth header, and the URL expires in up to an hour. It serves raw bytes of any size, so a binary .npy or .h5ad comes through unchanged. Spends no credit. 400 if the artifact is a directory rather than a file. 404 if the artifact isn't yours, or if its file is no longer in storage.
helical___getConfirmationStatus
ChatGPTPolls a confirmation_id returned by a tool that queued an action instead of running it. Read it to see whether the action is still pending, or was executed, rejected, expired or failed. Resolve a pending one with resolveConfirmation — this tool only reports, it never decides. 404 if the id isn't one of yours.
helical___getDagErrors
ChatGPTReturns the error raised by each failed task in a run, so you can tell the user what to fix. Only runs in your own project are readable. An empty errors list is not an error — a run may have failed without raising (killed, evicted, out of memory). Fall back to getRunDetails for state in that case. Spends no credit.
helical___getDataset
ChatGPTReturns the full DataScMeta (single-cell) record for one dataset, including the columns relevant for downstream trigger configuration (celltypeColumn, diseaseColumn, donorColumn, sexColumn, batchColumns). Sequence-RNA datasets are not served here. Use after listDatasets when the user picks a specific dataset and you need its full metadata. The tools that take a dataset take this id directly. Returns 404 if the dataset is missing, soft-deleted, or outside your projects. Spends no credit.
helical___getRunDetails
ChatGPTStatus, timing, input dataset and produced artifacts for one run of any type (finetuning, embedding, evaluation, perturbation, attention_analysis, or wrapper_perturbation_reports). Only runs in your own project are readable. A run that does not exist and a run you cannot read are indistinguishable — both 404. Poll this run until state is 'succeeded' or 'failed'; an in-flight run has no artifacts yet. used_dataset names the input the run consumed; child_runs lists the downstream runs that consumed its output. Fetch any artifact with downloadArtifact. Spends no credit.
helical___health
ChatGPTReturns { "status": "healthy" } when the surface is serving and the caller is authenticated. Takes no input, reads nothing, and changes nothing. Use it to confirm the connection works; it says nothing about whether any other tool will succeed. Probe: 1
helical___initiateDatasetUpload
ChatGPTStep 1 of 3 for putting a dataset file into a project: initiateDatasetUpload (this tool, including uploading every part it returns) → completeDatasetUpload → registerDataset. You must split the file yourself. S3 rejects chunked encoding on a presigned PUT, so streaming with curl -T - fails: materialise each part, upload it, then delete it (peak extra disk is one part, not a whole second copy). Slice by EXACT BYTES using each part's offsetBytes and lengthBytes. Do not convert them to MiB blocks — the final part is almost never a whole number of MiB, and rounding silently truncates it into a corrupt upload: tail -c +$((<offsetBytes> + 1)) ds.h5ad | head -c <lengthBytes> > part.N curl -T part.N '<that part's url>' && rm part.N (GNU dd alternative: dd if=ds.h5ad of=part.N bs=1M skip=<offsetBytes> count=<lengthBytes> iflag=skip_bytes,count_bytes.) Parts may be uploaded in any order, and you do NOT need to record ETags — the server collects them. Max 100 GiB. Presigned URLs expire after 6 hours; if that passes mid-upload, abort and start over.
helical___listDagRuns
ChatGPTReturns runs, newest first, with their current state. There is no project or owner parameter — you see your own runs and only those. Optional filters (dagIds, state, baseModel, tags, date range, …) narrow the list; multi-value ones are comma-separated. limit caps how many of the most-recent runs come back (default 50), and total_entries is how many matched in all. Each row's child_runs lists the downstream runs that consumed that run's output (lineage). Use this to see recent or in-flight jobs; to poll a single run, or to reach its artifacts, getRunDetails is cheaper. Spends no credit.
helical___listDatasets
ChatGPTReturns the single-cell (DataScMeta) dataset catalog the user can run analyses against. Sequence-RNA datasets are not returned here. Use this when the user asks 'what datasets do I have?' or to find a dataset's UUID before passing it to other tools. Pass the returned id as datasetId to the tools that take a dataset (they translate it to the on-disk path server-side). Only datasets in your projects are listed. Spends no credit. Optional filters (name, author, organism, tissue, disease, dataPath) AND together in a single call — each filter narrows the result set, no need to issue multiple calls. String fields (name, author, dataPath) match on a case-insensitive substring; array fields (organism, tissue, disease) match if the dataset's array contains the value exactly.
helical___listModels
ChatGPTReturns both kinds of model this listing covers. base_models is the foundation-model catalog — available immediately, no fine-tuning required. models is this workspace's registry of fine-tuned models, newest-promoted first. This is the single model-discovery surface. For a base_models entry, pass its name verbatim as a trigger tool's model and omit model_version. For a models entry, pass its name plus its version as model_version — NOT its base_model, which names the foundation it descends from. status applies to models only: a foundation model is neither promoted nor a promotion candidate, so it is never filtered by it. Defaults to all: every fine-tuned model in this workspace can launch, promoted or not. Every entry carries credits_per_cell and credits_per_job, so a run can be quoted before it is triggered: credits_per_job + cells × passes × credits_per_cell, where passes is 1 for an embedding and 6 × epochs for fine-tuning. A validation dataset adds its own cells × 1 × epochs. A fine-tuned model is charged at the rate of the foundation model it descends from, which is why its price follows its base_model. This listing covers single-cell models only.
helical___listPendingConfirmations
ChatGPTLists the actions queued under your project that are still waiting for a decision, newest first. Each entry carries the confirmation_id needed to poll it with getConfirmationStatus or settle it with resolveConfirmation, and, for a queued launch, a summary of what that run will do; for queued feedback, a summary holding the exact message. Any other action has summary: null and is named by target_label CALL THIS BEFORE RE-REQUESTING A QUEUED ACTION. A queuing tool that returns 409 (A pending approval for this operation already exists.) does not hand back the id, and this is the only way to recover it — re-requesting the action instead of listing will just 409 again. Only pending actions appear. One that was approved, rejected or expired drops out of this list; read its outcome with getConfirmationStatus. Past-due entries are already excluded, so the list is never stale.
helical___raiseFeedback
ChatGPTQueues a feedback message to the Helical team. Use it when the user asks to report something or send feedback. When you hit an obstacle — a tool error, a failed run, a missing capability, a blocked action — you may offer to raise feedback, once for that obstacle; do not offer again for it. ASK FIRST. Draft the message, show the user the exact text, and call this only after they agree to send it. Never call it on your own initiative. Include what was attempted, the failing tool or run id, and the error. The user, instance and this conversation or project are added for you. Nothing is sent by this call: it returns status: 'pending_approval' + a confirmation_id, and the feedback is sent only once approved. Show the user the exact message and approve it with resolveConfirmation only once they agree; on a 409, recover the pending one's id with listPendingConfirmations. 409 means a feedback message is already waiting for approval here; only one can be pending at a time. If the approved feedback ends failed, tell the user it was not delivered — for example, feedback is not configured on this instance.
helical___registerDataset
ChatGPTStep 3 of 3: creates the catalogue row for an object already uploaded via initiateDatasetUpload + completeDatasetUpload, making the dataset visible in the dashboard's Data tab and usable by the trigger tools. Pass the s3Key that completeDatasetUpload returned. Side effects: copies the uploaded file to the project's canonical dataset path and writes the catalogue row plus the project's access grant. 409 if the project already has a dataset with this name.
helical___resolveConfirmation
ChatGPTResolves a confirmation_id returned by a tool that queued an action instead of running it. approve executes the queued operation inline and returns once it has run, reporting what it did in outcome; reject discards it. This is the only place that outcome is returned ASK THE USER FIRST. When the queued action is a run, quote its cost: approving spends their credit. When it is feedback, show them the exact message from its summary: approving sends it. Otherwise name what it changes (target_label). Approval cannot be reversed from here — this call IS their approval, so never make it on your own initiative or to retry something they declined. Each confirmation resolves once. A second call on the same id — and one on an id that has already expired — 404s. Read the outcome later with getConfirmationStatus. A 402 means the user's balance could not cover the run, and a 400 saying the quote can no longer be spent means it is no longer usable — in both cases nothing was launched, the confirmation is spent, and the run must be re-requested from the tool that created it. 500 means it was approved but failed to run; it also stays resolved and must be re-queued. For a dataset action, 403, 404 or 409 on an id that was still pending means approval found the request no longer valid (write access lost, dataset deleted or no longer in the project, name taken): nothing changed, the confirmation is spent, and it must be re-requested. Check getConfirmationStatus first — failed means nothing changed; executed means an earlier call already ran it.
helical___triggerEmbedding
ChatGPTQueues an embedding run that produces embeddings for a single-cell dataset using a foundation (or fine-tuned) model. Use when the user asks to embed / extract representations / compute features from a dataset. Does NOT launch directly. ASK THE USER BEFORE APPROVING: the run consumes GPU compute in their account, and where billing is enabled it spends their credit. The run is queued for your own approval and starts only once you approve it. Returns status: 'pending_approval' + a confirmation_id; approve or reject it with resolveConfirmation, and read its outcome with getConfirmationStatus. Sequence models are refused: this tool embeds the single-cell datasets listDatasets returns.
helical___triggerFinetuning
ChatGPTQueues a fine-tuning run. One model per call. Use this when the user asks to fine-tune a model — for example: 'fine-tune scGPT on the lung dataset with label LVL3'. labels, task_type, and model_type are parallel arrays — one entry per task. Commonly-successful values (from prior successful runs; guidance, not hard limits): learning_rate 1e-4, num_trainable_layers 1–2, batch_size 16, weight_decay 0.01, lr_scheduler 'constant', seed 42; start with epochs 1 and increase only if under-fit. The price counts 6 passes per epoch over each training cell, plus 1 per epoch over each cell of the valDatasetId dataset if one is given, at the model's per-cell rate from listModels. So a fine-tune costs many times an embedding of the same dataset, and epochs is the term to reason about. A hyperparameter search is not offered here: one run trains one configuration. Validation runs once an epoch over the dataset valDatasetId names, and the quote counts its cells; datasets arrive pre-split, so val_split is not offered, nor is a per-step validation cadence. Does NOT launch directly. ASK THE USER BEFORE APPROVING: the run consumes GPU compute in their account, and where billing is enabled it spends their credit. The run is queued for your own approval and starts only once you approve it. Returns status: 'pending_approval' + a confirmation_id; approve or reject it with resolveConfirmation, and read its outcome with getConfirmationStatus.
helical___triggerPerturbation
ChatGPTQueues a perturbation run that predicts, with PerturbGen's decoder, how masking a gene changes a labeled .h5ad dataset's cells at later time points. Use when the user asks what masking a gene would do to cells at later time points — for example: 'mask IL1B in the 90-minute LPS cells and predict them at 6 h and 10 h'. Generation is estimator: 'perturbgen', the one estimator this tool offers. Each gene in target_genes is masked in every source cell that holds it, and the decoder predicts each cell at every time point in perturbgen_config.pred_tps. The edit is fixed to a mask, so there are no regulation factors to choose. Cells: group_obs_key and groups_to_perturb pick the source cells, and n_cells_perturbed (at most 2000) samples them. The quote charges two runs per gene for every source cell, unedited and masked, and one more run per source cell for the gene embeddings. The unedited run is the control. The model shares one unedited run per cell across the genes and decodes only the cells holding each gene, so the quote carries a margin over the work done. Each run is one encoder pass plus one decoder pass per time point in perturbgen_config.pred_tps (default 1, 2), and the quote charges each decoder pass as 15 passes. perturbgen_config.n_samples count draws, at most 100, are averaged per predicted cell; the quote does not charge for them. Genes: only genes in the decoder's 1,856-gene LPS vocabulary can be masked. A gene outside the vocabulary or the dataset counts as missing and is dropped, and the run fails when more than 20% of target_genes are missing. A symbol and its Ensembl id name one gene, so listing both fails the run. The quote counts every listed gene. One run per call; for several gene lists, make N calls. Follow the run with listDagRuns / getRunDetails; once it succeeds, getRunDetails lists what it produced and downloadArtifact fetches any of those files. Does NOT launch directly. ASK THE USER BEFORE APPROVING: the run consumes GPU compute in their account, and where billing is enabled it spends their credit. The run is queued for your own approval and starts only once you approve it. Returns status: 'pending_approval' + a confirmation_id; approve or reject it with resolveConfirmation, and read its outcome with getConfirmationStatus.
helical___updateDataset
ChatGPTQueues an edit to a dataset's name or descriptive metadata. Nothing changes until resolveConfirmation approves the returned confirmation_id. Spends no credit. Send only the fields to change. A list field replaces the stored list rather than adding to it, and null clears donorCount, link, linkPublication, linkData or licence. Measured counts, the file location, status and .obs column names cannot be edited here. 400 if the body is empty or names a field this tool does not accept. 404 if the dataset doesn't exist or is deleted. 403 if the user has read-only access. 409 if the new name is taken, or an edit of this dataset is already queued — recover its confirmation_id with listPendingConfirmations.
helical___whoami
ChatGPTAnswers 'who am I signed in as', and 'how much credit do I have left' credits_balance moves as runs are charged, so read it again rather than reusing an earlier figure. console is where a human goes to act on any of this.
