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.pyEverything 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.
| Option | Description |
|---|---|
--title | The 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. |
--description | Replaces the code's description. |
--category | Replaces the code's category. |
--tag | Added to the code's tags. Repeatable. |
--group | Replaces 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. |
--config | The run's config: a JSON object, or the path to a JSON file. |
--dataset PATH=NAME | A dataset to register on the run, and upload, once the command succeeded. Repeatable. |
--model PATH=NAME | A model, the same way. Repeatable. |
--project, -p | The project, organisation/name. |
--prompt | Ask 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.shA 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 Nas its traceback, not a Python one. - For a command that opens no run, the run lists the packages of the environment
hlabruns in, and names no Python. That is right withuv run hlab launch, and wrong withuvx 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:
| Variable | Description |
|---|---|
HECTIQLAB_RUN_TITLE | The first run's title. |
HECTIQLAB_RUN_DESCRIPTION | Its description. |
HECTIQLAB_RUN_CATEGORY | Its category. |
HECTIQLAB_RUN_TAGS | Tags added to its own, comma-separated: TRA-20,backfill. |
HECTIQLAB_RUN_GROUP | The id of the group it joins. |
HECTIQLAB_RUN_CONFIG | Config under its own, when it joins a run hlab launch opened. Ignored otherwise. A JSON object, or the path to a JSON file. |
HECTIQLAB_PROMPT | What asks on the terminal. See Settings. |