Metadata-Version: 2.5
Name: hectiqlab
Version: 0.4.0
Summary: Record runs, stages, metrics, datasets and models to Hectiq Lab, from a script or the command line.
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13.7
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: cli
Requires-Dist: typer>=0.12; extra == 'cli'
Provides-Extra: gcs
Requires-Dist: google-cloud-storage>=3.2; extra == 'gcs'
Provides-Extra: parquet
Requires-Dist: pyarrow>=15; extra == 'parquet'
Provides-Extra: tui
Requires-Dist: textual-plotext>=1.0; extra == 'tui'
Requires-Dist: textual>=8.2; extra == 'tui'
Requires-Dist: typer>=0.12; extra == 'tui'
Description-Content-Type: text/markdown

# Hectiq Lab

Track your machine learning experiments in [Hectiq Lab](https://lab.hectiq.ai): runs, metrics, datasets and models, from Python or the command line.

- **Out of your way.** Everything is sent in the background, and an API that is down never crashes your training.
- **Nothing to fill in.** Each run records its commit, diff, packages and machine by itself.
- **Built for agents too.** Every `hlab` command prints JSON with `--json`.
- **A dashboard in your terminal.** `hlab ui` follows your runs live.

The documentation is at [docs.hectiq.ai](https://docs.hectiq.ai/hectiqlab/).

## Installation

```bash
pip install "hectiqlab[cli]"
```

This gives you the Python package and the `hlab` command line. Other installs:

```bash
pip install hectiqlab                 # the Python package only, e.g. on a training machine
pip install "hectiqlab[tui]"          # adds the dashboard, hlab ui
pip install "hectiqlab[tui,parquet]"  # adds parquet previews in the dashboard
```

## Quickstart

Log in once per machine, with the email and password you use on the web app:

```bash
hlab login
```

Then choose the project this repository records to:

```bash
hlab init hectiq-ai/demo
```

Now record a run:

```python
import hectiqlab as hl

with hl.run("My first run", config={"lr": 1e-3, "epochs": 3}):
    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="my-model")
```

The run ends `completed`, or `failed` with its traceback if the block raises. Find it in the web app, or with `hlab run list`.

## Command line

```bash
hlab run list                   # the project's runs
hlab run get 42                 # one run, by its number
hlab metric get 42 loss         # a metric's values
hlab model download my-model    # a model's files
hlab launch --tag ENG-42 -- python train.py   # record a command, and say how
hlab --help                     # everything else
```

Add `--json` to any command to get JSON on stdout.

## Dashboard

```bash
hlab ui
```

It opens on your project. Press `?` to see the keys.

## Settings

| Variable | What it does |
|---|---|
| `HECTIQLAB_API_KEY` | Your key, instead of `hlab login`. Useful where the command line isn't installed. |
| `HECTIQLAB_PROJECT` | The project, instead of `hlab init`. You can also pass `project=` to `hl.run`. |
| `HECTIQLAB_DISABLE=1` | Records nothing. In distributed training, only rank 0 records anyway. |
