Skip to main content

hectiqlab

Record runs, stages, metrics, datasets and models to Hectiq Lab, from a training script or the command line. Everything goes to the API the web app reads, over HTTP, from one background thread, so a training loop never waits on the network.

This package lives beside pyhectiqlab (in sdk/) and does not replace it: both can be installed together, and they share ~/.hectiq-lab/credentials.toml.

pip install hectiqlab                 # the SDK
pip install "hectiqlab[cli]"          # and the `hlab` command line
pip install "hectiqlab[tui]"          # and the dashboard `hlab ui` opens
pip install "hectiqlab[tui,parquet]"  # and parquet previews in it, which take pyarrow

A script

import hectiqlab as hl

with hl.run(
    "two-tower, 3 epochs",
    category="training",
    tags=["linear:ENG-42"],
    config={"lr": 1e-3, "epochs": 3},
):
    data = hl.datasets.get("interactions").unwrap()
    hl.datasets.attach(data.id)
    with hl.stage("train"):
        for epoch in hl.each(range(3), "epoch"):
            loss = train_one_epoch()
            hl.add_metric("loss", step=epoch, value=loss)
    hl.models.create("checkpoints/", name="two-tower").result()

A run captures its commit, branch, diff, installed packages, machine and command line as it opens, and ends completed, failed (with its traceback) or stopped, whether it was opened with with or left open until the script crashed or exited. One exit it cannot see: a run opened without with in a script that calls sys.exit(1) ends completed, because Python never hands a SystemExit to the exception hook; open the run with with to record the exit status. Stages nest: a with, a decorated function or a named each opens a stage inside whatever is open. Reads and changes return a Result; uploads and downloads return a Future, and an upload made while a run is open holds the run open until it lands, however long that takes (the bar shows it moving; Ctrl-C ends the run stopped without it).

An API that is down, slow or refusing never raises in the middle of a training loop: a failed read or change is an Err, and what a run recorded that did not land is said once, as a warning, when the run closes (run.result() raises it instead). A mistake in the call itself does raise, at once: a metric or a stage with no run open, a category the web app does not know.

Uploads and downloads draw a progress bar on stderr when it is a terminal. progress=False on the call, or HECTIQLAB_PROGRESS=false, draws none; progress=True draws one anyway.

The project comes from project=, hl.set_project(...), HECTIQLAB_PROJECT, or the .hectiqlab/config.toml that hlab init writes. HECTIQLAB_DISABLE=1, or a RANK/LOCAL_RANK other than 0, records nothing.

A tag written linear:ENG-42 speaks to that Linear issue, and linear:project:<slug> to a Linear project (the slug is the end of the project's Linear address). A run carrying one comments there when it starts, when it ends, and when the tag is attached; a dataset or a model version comments when such a tag is attached to it, which is how a deliverable is marked. Creating a version or removing a tag says nothing, and a bare ENG-42 or GPT-4 never speaks to Linear. The key belongs to the project, since a client's project comments in the client's Linear: hlab login --linear -p org/project keeps it in the credentials file as [linear."org/project"], and LINEAR_API_KEY overrides it for one process. A project without a key comments nowhere; there is no key shared by every project.

The command line

hlab login                      # make a key with your email and password
hlab init hectiq-ai/recsys      # this checkout records to that project
hlab run list --tag linear:ENG-42
hlab run get 42 --json          # runs are named by their rank, or their id
hlab run stages 42
hlab run tag 42 best            # dataset and model tag the same way
hlab metric get 42 loss
hlab dataset create data/ --name interactions --no-upload
hlab model download two-tower --version 1.3
hlab artifact get art_4f2c

Every command that reads or changes something takes --json, and prints one JSON document on stdout; prompts and progress bars go to stderr.

The dashboard

hlab ui opens a terminal dashboard onto a project, hectiqlab.tui; ? lists the keys. It opens on the project the SDK would record to (-p, HECTIQLAB_PROJECT, or .hectiqlab/config.toml), and on the switcher when nothing names one; P switches from anywhere. 1 to 5 are the dashboard, runs, datasets, models and tags.

Everything it shows comes from the API the web app reads, through the SDK's own read functions: it refreshes every second, and reads the series of the open runs and of those that ended in the last fourteen days, a hundred runs to a request. It reads only the series on screen: an older run's come when it is opened. An open run that has given no sign of life for an hour, no change to its row, no sample, no stage, is shown as silent and read once a minute. A file previews over its signed address a range at a time, so a 20 GB parquet shows its schema, its row count and its first rows without being downloaded; without the parquet extra, a parquet says what to install instead.

A screen (tui/screens/, built from tui/widgets/) never calls the SDK. It asks tui/reads/, and draws the SDK's own records. Importing hectiqlab never imports the dashboard.

Development

cd sdk_v2
uv sync
uv run ruff check . && uv run ruff format --check . && uv run ty check && uv run lint-imports
uv run pytest -m "not integration"

The integration tests talk to the API running in api/compose.yaml, logged in as the user they seed it with, whose email and password come from your environment. They are skipped when the stack is not up or the login is not set, and fail instead with HECTIQLAB_INTEGRATION=required, as in CI:

docker compose -f ../api/compose.yaml up -d --build
export HECTIQLAB_TEST_EMAIL=you@example.com HECTIQLAB_TEST_PASSWORD=...  # 8+ chars, upper, lower, digit
uv run pytest -m integration

The stack, its login, the fresh key and project each test gets, and the clean process every test starts from are in testing/hectiqlab_stack.py, a pytest plugin every test loads. It is not part of the wheel. The dashboard's tests, in tests/tui/, read a seeded project instead of the API, except those in tests/tui/integration/.

On a pull request that touches api/ or sdk_v2/, .github/workflows/hectiqlab_checks.yml runs these checks and the unit tests on Python 3.10 and 3.13, and the integration tests against one stack.

Releasing

hectiqlab is one package, the SDK, the command line and the dashboard at one version. A release is one button: Actions → Release hectiqlab → Run workflow on main, picking patch, minor or major (or gh workflow run release_hectiqlab.yml -f bump=minor).

The workflow (.github/workflows/release_hectiqlab.yml) runs the checks, including the integration tests; moves the version and re-locks; builds the package and checks its metadata; commits Release hectiqlab X.Y.Z to main and tags it hectiqlab-vX.Y.Z; creates the GitHub release with the subjects of the commits under sdk_v2/ since the last release; then publishes it to PyPI. Nobody edits a version by hand. If only the publishing fails, re-running that job publishes the distributions already built.

The version steps live in .github/scripts/release_hectiqlab.py, which runs the same on a clone (bump, notes, check).

Once, before the first release, and close together, because a pending publisher does not reserve the name (PyPI docs):

  1. On pypi.org, under your account's Publishing page, add a GitHub Actions pending publisher for the project hectiqlab: repository HectiqAI/hectiq-lab-revision, workflow release_hectiqlab.yml, environment pypi.
  2. In the repository's settings, create the pypi environment. Required reviewers on it make every release wait for an approval before it publishes.
  3. Run the first release. It ships the version the pyproject already declares, 0.1.0, whichever bump is picked; every release after it bumps.

Metadata

Release files for hectiqlab 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hectiqlab 0.1.0
File Size Uploaded Provenance Actions
hectiqlab-0.1.0.tar.gz 259.4 kB With provenance Details for hectiqlab-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hectiqlab 0.1.0
File Interpreter ABI Platform Actions
hectiqlab-0.1.0-py3-none-any.whl Python 3 none any Details for hectiqlab-0.1.0-py3-none-any.whl

Total release size: 476.4 kB

Release files / hectiqlab-0.1.0.tar.gz

Download URL hectiqlab-0.1.0.tar.gz
Size 259.4 kB
Tags Source
SHA-256 checksum
How to use checksums
2cce15ea8ea5a150a4149cbc93a61f9e5d40a400113e80c6ff6663dc44d8a7d8
BLAKE2b-256 checksum
How to use checksums
a5190b91f4df802899be2473d4666187c843c9bb2b2480caa9c80dd0e23182ff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.

Transparency log

Release files / hectiqlab-0.1.0-py3-none-any.whl

Download URL hectiqlab-0.1.0-py3-none-any.whl
Size 217.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2194b242f4f858e35a6e1e13bce4c903692e005748b5de9d5e1d5f1e69c5eecd
BLAKE2b-256 checksum
How to use checksums
6636242cba21d937334a80fc4b5123a052b5a1a2d5db71c6870522d3a140c34d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.

Transparency log

Security for hectiqlab 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hectiqlab-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page