Hectiq Lab

Launch

Run a command as one run, and say at launch how it's recorded.

hlab launch runs a command and records it as one run, whether the command calls hectiqlab or not. From the command line, it sets the run's title, description, category, tags, group and config, and which datasets and models to register. It never changes what the work recorded. Metrics, artifacts and stages stay as the code made them.

hlab launch --title "Backfill, March" --tag TRA-20 --category evaluation -- python train.py

Everything after -- is the command, run as it is. hlab launch exits with the command's own exit code, so a pipeline sees what it would see without it. With the SDK switched off, it only runs the command.

The run

The run opens before the command starts, with the command as its entrypoint. It ends the way the command ended: completed on exit code 0, failed otherwise, and stopped on Ctrl-C, which reaches the command too.

OptionDescription
--titleThe run's title, over the code's. Without it, hlab launch asks for one on a terminal, and refuses to run the command off one.
--descriptionReplaces the code's description.
--categoryReplaces the code's category.
--tagAdded to the code's tags. Repeatable.
--groupReplaces the code's group: the group's id, or a title, found or made as hl.group does, before the command starts. A group it made is said.
--configThe run's config: a JSON object, or the path to a JSON file.
--dataset PATH=NAMEA dataset to register on the run, and upload, once the command succeeded. Repeatable.
--model PATH=NAMEA model, the same way. Repeatable.
--project, -pThe project, organisation/name.
--promptAsk on the terminal for everything, as HECTIQLAB_PROMPT=all says. See Settings.

Nothing is registered after a failure.

hlab launch --title "Nightly export" --dataset out/rows.parquet=rows -- ./export.sh

A script that opens a run

The first hl.run the script opens joins the launch's run instead of opening a second one. The runs after it open as the code says.

The launch's options win over the code's. Where the launch says nothing, the code's description, category and group land on the run. Tags from both land on it. Its config goes over the one from --config: where both set a key, the code wins, because the code knows what it ran with. Its packages, command line, stages, metrics and traceback land on the run too, and hlab launch ends it.

What a launch can't see

  • A command that makes no SDK call records no metric and no stage.
  • A command that fails without the SDK leaves exited with code N as its traceback, not a Python one.
  • For a command that opens no run, the run lists the packages of the environment hlab runs in, and names no Python. That is right with uv run hlab launch, and wrong with uvx hlab launch.

Ask on the terminal

--prompt asks on the terminal for everything, for this launch: the run, and the datasets and models the command and --dataset and --model create. The command inherits it. To ask for some kinds only, set HECTIQLAB_PROMPT instead: HECTIQLAB_PROMPT=runs hlab launch .... When the prompt asks for runs, it asks for the run's title, tags and category before the command starts, and whether to keep the run once the command and its outputs are done. An empty title is refused. See Settings for what each kind asks.

Without hlab launch

The options reach the command as environment variables, which it inherits. A CI job can set them and run python train.py directly. Its first run then opens as usual, with what they say:

VariableDescription
HECTIQLAB_RUN_TITLEThe first run's title.
HECTIQLAB_RUN_DESCRIPTIONIts description.
HECTIQLAB_RUN_CATEGORYIts category.
HECTIQLAB_RUN_TAGSTags added to its own, comma-separated: TRA-20,backfill.
HECTIQLAB_RUN_GROUPThe id of the group it joins.
HECTIQLAB_RUN_CONFIGConfig under its own, when it joins a run hlab launch opened. Ignored otherwise. A JSON object, or the path to a JSON file.
HECTIQLAB_PROMPTWhat asks on the terminal. See Settings.

On this page