Metadata-Version: 2.4
Name: embedl-hub
Version: 0.0.2
Summary: The official Embedl Hub Python client library.
Author-email: Embedl AB <support@embedl.com>
Project-URL: Homepage, https://hub.embedl.com
Project-URL: Documentation, https://hub.embedl.com/docs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: asyncssh>=2.22.0
Requires-Dist: packaging>=21.0
Requires-Dist: platformdirs>=4.5
Requires-Dist: pydantic>=2.8.2
Requires-Dist: PyYAML~=6.0.2
Requires-Dist: requests>=2.32.3
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12.0
Requires-Dist: typing-extensions>=4.15.0
Provides-Extra: tflite
Requires-Dist: ai-edge-litert==2.1.4; (sys_platform != "linux" or platform_machine != "aarch64") and extra == "tflite"
Requires-Dist: ai-edge-quantizer==0.6.0; (sys_platform != "linux" or platform_machine != "aarch64") and extra == "tflite"
Requires-Dist: onnx~=1.18.0; extra == "tflite"
Requires-Dist: onnx2tf==1.28.3; (sys_platform != "linux" or platform_machine != "aarch64") and extra == "tflite"
Requires-Dist: onnx_graphsurgeon==0.5.8; (sys_platform != "linux" or platform_machine != "aarch64") and extra == "tflite"
Requires-Dist: onnxsim>=0.4.33; (sys_platform != "linux" or platform_machine != "aarch64") and extra == "tflite"
Requires-Dist: psutil>=5; (sys_platform != "linux" or platform_machine != "aarch64") and extra == "tflite"
Requires-Dist: qai-hub>=0.40.0; extra == "tflite"
Requires-Dist: sng4onnx==1.0.4; (sys_platform != "linux" or platform_machine != "aarch64") and extra == "tflite"
Requires-Dist: tf_keras==2.21.0; (sys_platform != "linux" or platform_machine != "aarch64") and extra == "tflite"
Provides-Extra: onnxruntime
Requires-Dist: onnx~=1.18.0; extra == "onnxruntime"
Requires-Dist: qai-hub>=0.40.0; extra == "onnxruntime"
Provides-Extra: tensorrt
Requires-Dist: onnx~=1.18.0; extra == "tensorrt"
Provides-Extra: all
Requires-Dist: embedl-hub[onnxruntime,tensorrt,tflite]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: docs
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-click; extra == "docs"
Dynamic: license-file

# Embedl Hub Python library

`embedl-hub` is the official Python client for
[Embedl Hub](https://hub.embedl.com) — a platform for compiling, profiling, and
tracking machine learning models for edge devices.

The `embedl-hub` command-line tool takes a model from your machine to a real
device and records every step along the way:

- **Compile** a model for on-device execution through the TFLite, ONNX Runtime,
  or TensorRT toolchains.
- **Profile** latency and memory on a real device — in a device cloud, or on
  your own hardware over SSH.
- **Invoke** a compiled model on a device to run inference on real input data.
- **Track** every run, with its parameters, metrics, tags, and artifacts, in
  your Embedl Hub project — from the shell, or from your own Python code.

Each command records a run on [Embedl Hub](https://hub.embedl.com), so the
artifact produced by one step feeds straight into the next and your results stay
comparable and reproducible later.

- Guides and setup: <https://hub.embedl.com/docs>
- Create an account: <https://hub.embedl.com/docs/setup>

## Requirements

Python 3.10 or newer.

## Installation

```shell
pip install embedl-hub
```

The base install covers the tracking API and the whole run-control CLI — `auth`,
`init`, `show`, `use`, `run`, `log`, `batch`, and `list-devices` — and pulls in
no backend execution toolchain.

`compile`, `profile`, and `invoke` wrap external toolchains, so each one lives
behind an extra:

| Toolchain    | Install command                         |
| ------------ | --------------------------------------- |
| TFLite       | `pip install 'embedl-hub[tflite]'`      |
| ONNX Runtime | `pip install 'embedl-hub[onnxruntime]'` |
| TensorRT     | `pip install 'embedl-hub[tensorrt]'`    |
| Everything   | `pip install 'embedl-hub[all]'`         |

Run a command whose extra is not installed and the CLI prints the `pip install`
line you need, instead of an import traceback.

On Linux aarch64, `[tflite]` skips the `onnx2tf`-based local conversion path and
the `ai-edge-*` quantization dependencies, because the upstream TensorFlow
package publishes no Linux aarch64 wheels. The Qualcomm AI Hub TFLite provider
still works on that platform.

## Getting started

Create an API key under **Personal API keys** on your
[Embedl Hub profile page](https://hub.embedl.com/profile), then store it:

```shell
embedl-hub auth --api-key <your-key>
```

The key can also be supplied through the `EMBEDL_HUB_API_KEY` environment
variable.

Choose the project your runs are recorded in, and check the active context:

```shell
embedl-hub init --project my-project
embedl-hub show
```

### Track a run from the shell

`run start` creates a run and prints its ID to stdout, so a shell script can
capture it and log against it:

```shell
run=$(embedl-hub run start --type eval --name "Evaluate baseline")

embedl-hub log param    --run "$run" model resnet18
embedl-hub log metric   --run "$run" accuracy 0.923 --step 1
embedl-hub log artifact --run "$run" results/predictions.json

embedl-hub run finish "$run"
```

Or bind the run to the current directory with `--use`, and drop `--run`
everywhere after that:

```shell
embedl-hub run start --type eval --use
embedl-hub log metric accuracy 0.923 --step 1
embedl-hub log tag stage baseline
embedl-hub run finish
```

`embedl-hub use` prints the defaults in effect and where each one came from;
`use run`, `use project`, and `use batch` set them, and `use clear` removes
them. `EMBEDL_HUB_RUN`, `EMBEDL_HUB_PROJECT`, and `EMBEDL_HUB_BATCH` override
the directory defaults, which makes the same scripts work unchanged in CI.

Read runs back without leaving the terminal:

```shell
embedl-hub run list                # the project's runs, newest first
embedl-hub run show "$run"         # one run with everything logged on it
embedl-hub run url "$run"          # its address on the hub
```

`run list --failed`, `--all`, and `-n/--limit` narrow the listing, and both
`run list` and `run show` take `--json` for scripting.

### Batch logging

When a job logs a lot, or runs somewhere without reliable network, queue the
entries locally and send them in one request afterwards:

```shell
embedl-hub batch start --name "epoch metrics" --use
embedl-hub log metric accuracy 0.91 --step 1
embedl-hub log metric accuracy 0.93 --step 2
embedl-hub batch send
```

`batch show` inspects a queue before sending, `batch list` shows the queues on
this machine, and `batch discard` drops one. A single `log` command can bypass
an active batch with `--no-batch`.

### Take a model to a device

List the devices you can target:

```shell
embedl-hub list-devices
```

Compile a model, then profile what you just compiled. `--from-run latest` picks
up the artifact from the previous run, so there are no files to move by hand:

```shell
pip install 'embedl-hub[tflite]'

embedl-hub compile tflite qai-hub -m model.onnx -s 1,3,224,224 -d "Samsung Galaxy S24"
embedl-hub profile tflite qai-hub --from-run latest -d "Samsung Galaxy S24"
```

## Commands

| Command                   | Purpose                                          | Base install     |
| ------------------------- | ------------------------------------------------ | ---------------- |
| `embedl-hub auth`         | Store your API key.                              | yes              |
| `embedl-hub init`         | Set the project and artifact directory.          | yes              |
| `embedl-hub show`         | Print the active project and artifact directory. | yes              |
| `embedl-hub use`          | Bind default targets to the current directory.   | yes              |
| `embedl-hub run`          | Start, finish, and inspect runs.                 | yes              |
| `embedl-hub log`          | Log metrics, params, tags, links, and artifacts. | yes              |
| `embedl-hub batch`        | Queue log entries locally and send them later.   | yes              |
| `embedl-hub list-devices` | List available target devices.                   | `embedl` devices |
| `embedl-hub compile`      | Compile a model for on-device execution.         | needs an extra   |
| `embedl-hub profile`      | Measure latency and memory on a device.          | needs an extra   |
| `embedl-hub invoke`       | Run inference on a compiled model.               | needs an extra   |

`run`, `log`, `batch`, and `use` group their own subcommands:

| Group   | Subcommands                                     |
| ------- | ----------------------------------------------- |
| `run`   | `start`, `finish`, `list`, `show`, `set-parent`, `url` |
| `log`   | `metric`, `param`, `tag`, `link`, `artifact`    |
| `batch` | `start`, `send`, `show`, `list`, `discard`      |
| `use`   | `run`, `project`, `batch`, `clear`              |

`compile`, `profile`, and `invoke` each take a toolchain, then a provider:

| Command   | TFLite             | ONNX Runtime                    | TensorRT  |
| --------- | ------------------ | ------------------------------- | --------- |
| `compile` | `local`, `qai-hub` | `qai-hub`, `embedl-onnxruntime` | `trtexec` |
| `profile` | `qai-hub`, `aws`   | `qai-hub`, `embedl-onnxruntime` | `trtexec` |
| `invoke`  | `qai-hub`          | `qai-hub`, `embedl-onnxruntime` | `trtexec` |

The `embedl-onnxruntime` and `trtexec` providers run on your own hardware over
SSH; the others use a device cloud. `embedl-hub list-devices qai-hub` lists the
Qualcomm AI Hub catalogue and needs the `[onnxruntime]` extra.

Run `embedl-hub --help`, or `--help` on any command, for the full option list.
The package installs two equivalent entry points: `embedl-hub` and `ehub`.

## Tracking from Python

The tracking API is part of the base install and writes to the same projects and
runs as the CLI, so you can log directly from your training or evaluation code:

```python
from embedl_hub.tracking import Client

client = Client()
client.set_project("my-project")

with client.start_run("eval", name="Evaluate baseline"):
    client.log_param("model", "resnet18")
    client.log_param("dataset", "imagenet-val")

    client.log_metric("accuracy", 0.923, step=1)
    client.log_metric("latency_ms", 8.4, step=1)

    client.log_tag("stage", "baseline")
    client.log_artifact("results/predictions.json")
```

`start_run` is a context manager: the run is finished for you on the way out,
marked failed if the block raises, and killed if you interrupt it. Parameters
take string values, metrics take floats with an optional `step`, and
`log_artifact` uploads a local file to the run. The run type is a string or a
member of `RunType`, also exported from `embedl_hub.tracking`.

Open the project on [Embedl Hub](https://hub.embedl.com) to see the run and
everything logged to it.

The compile, profile, and invoke components are available as Python classes too,
but each needs the extra for its toolchain installed. See the
[documentation](https://hub.embedl.com/docs) for those.

## Project status

`embedl-hub` is under active development. The public API may change between
releases in the 0.0.x series, so pin an exact version if you need a reproducible
build.

## Support

For questions, bug reports, and feedback, contact <support@embedl.com>.

## License

This software is subject to the
[Embedl Hub Software License Agreement](https://hub.embedl.com/embedl-hub-sla.txt).
