Metadata-Version: 2.4
Name: hubai-sdk
Version: 0.3.2
Summary: SDK for HubAI.
Author-email: Luxonis <support@luxonis.com>
Maintainer-email: Luxonis <support@luxonis.com>
License-Expression: Apache-2.0
Project-URL: repository, https://github.com/luxonis/hubai-sdk
Project-URL: issues, https://github.com/luxonis/hubai-sdk/issues
Keywords: ml,onnx,openvino,nn,ai,embedded
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: luxonis-ml[nn_archive,telemetry]~=0.9.0
Requires-Dist: keyring
Requires-Dist: requests
Requires-Dist: cyclopts
Requires-Dist: loguru
Requires-Dist: rich
Requires-Dist: packaging
Requires-Dist: onnx
Requires-Dist: psutil
Requires-Dist: pillow
Provides-Extra: dev
Requires-Dist: openapi-python-client; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: datamodel-code-generator; extra == "dev"
Requires-Dist: pydoctor~=25.10; extra == "dev"
Dynamic: license-file

# HubAI SDK

Python SDK for interacting with Luxonis HubAI, a platform for
managing, converting, and deploying machine learning models for
Luxonis OAK devices. If you want to convert models locally, check out
[modelconverter](https://github.com/luxonis/modelconverter) instead.

API documentation is available at <https://luxonis.github.io/hubai-sdk/>.

## ✨ Features

- **Model Management**: Create, list, update, and delete HubAI models
- **Variant Management**: Manage HubAI model variants and versions
- **Instance Management**: Create and manage HubAI model instances
- **Model Conversion**: Convert HubAI models to various formats including:
  - `RVC2`
  - `RVC3`
  - `RVC4`
  - `Hailo`
- **CLI Tools**: Command-line interface for all operations
- **Type Safety**: Full type hints for better developer experience

## 📦 Installation

Install the package using pip:

```bash
pip install hubai-sdk
```

Or install from source:

```bash
git clone https://github.com/luxonis/hubai-sdk.git
cd hubai-sdk
pip install -e .
```

## 📋 Requirements

- Python 3.10 or higher
- Valid Luxonis HubAI API key available from
  [HubAI Team API Key Settings](https://hub.luxonis.com/team-settings/api-keys)

## 🔐 Authentication

### Get Your API Key

1. Visit [HubAI Team API Key Settings](https://hub.luxonis.com/team-settings/api-keys)
2. Generate or copy your API key

### Set API Key

You can authenticate in several ways:

**Option 1: Environment Variable**

```bash
export HUBAI_API_KEY="your-api-key-here"
```

This will store the API key in your environment variable and will be used by the SDK automatically. It is valid for the current session only.

**Option 2: CLI Login**

```bash
hubai login
```

This opens a browser where you can generate a new API key and then
prompts you to enter it for secure local storage. Use
`hubai login --relogin` to replace an existing key, or `hubai logout`
to remove it.

**Option 3: Pass API Key Directly**

```python
from hubai_sdk import HubAIClient

client = HubAIClient(api_key="your-api-key-here")
```

## 🚀 Quick Start

### Python SDK Usage

```python
import os

from hubai_sdk import HubAIClient

# Initialize client
api_key = os.getenv("HUBAI_API_KEY")
client = HubAIClient(api_key=api_key)

# List all models
models = client.models.list_models()
print(f"Found {len(models)} models")

# Get a specific model
model = client.models.get_model(models[0].id)
print(f"Model: {model.name}")

# Convert a model to RVC2 format
response = client.convert.RVC2(
    path="/path/to/your/model.onnx",
    name="my-converted-model",
)

print(f"Converted model downloaded to: {response.downloaded_path}")
```

## 🛠️ Services

The SDK provides four main services accessible through the `HubAIClient`:

### Using Slugs from HubAI

You can copy slugs directly from the HubAI platform and use them as
identifiers in the SDK for models and variants:

```bash
hubai model info luxonis/yolov6-nano:r2-coco-512x384
```

### 🤖 Models Service (`client.models`)

Manage ML models in HubAI.

```python
# List models
models = client.models.list_models(
    tasks=["OBJECT_DETECTION"],
    is_public=True,
    limit=10,
)

# Get model by ID or slug (e.g., "luxonis/yolov6-nano:r2-coco-512x384")
model = client.models.get_model("model-id-or-slug")

# Create a new model
new_model = client.models.create_model(
    name="my-model",
    license_type="MIT",
    is_public=False,
    description="My awesome model",
    tasks=["OBJECT_DETECTION"],
)

# Update a model
updated_model = client.models.update_model(
    model.id,
    license_type="Apache 2.0",
    description="Updated description",
)

# Delete a model
client.models.delete_model(model.id)
```

### 🔄 Variants Service (`client.variants`)

Manage model variants and versions.

```python
# Assume `model` is a `ModelResponse`.

# List variants (optionally filtered by model)
variants = client.variants.list_variants(model_id=model.id)

# Get variant by ID or slug (e.g., "luxonis/yolov6-nano:r2-coco-512x384")
variant = client.variants.get_variant("variant-id-or-slug")

# Create a new variant
new_variant = client.variants.create_variant(
    name="my-variant",
    model_id=model.id,
    variant_version="1.0.0",
    description="First version",
)

# Delete a variant
client.variants.delete_variant("variant-id")
```

### 📦 Instances Service (`client.instances`)

Manage model instances (specific configurations of variants).

```python
from hubai_sdk.utils.types import ModelType

# Create an instance
instance = client.instances.create_instance(
    name="my-instance",
    variant_id="variant-id",
    model_type=ModelType.ONNX,
    input_shape=[1, 3, 288, 512],
)

# Upload a file to instance
client.instances.upload_file("/path/to/nn_archive.tar.xz", instance.id)

# Get instance config
config = client.instances.get_config(instance.id)

# Download instance
downloaded_path = client.instances.download_instance(instance.id)

# Delete instance
client.instances.delete_instance(instance.id)
```

### ⚡ Conversion Service (`client.convert`)

Convert models to various formats.

#### RVC2 Conversion

Convert models for Luxonis OAK devices:

```python
response = client.convert.RVC2(
    path="/path/to/model.onnx",
    name="converted-model",
    compress_to_fp16=True,
    number_of_shaves=8,
    superblob=True,
)
```

#### RVC4 Conversion

Convert models to Qualcomm SNPE format:

```python
response = client.convert.RVC4(
    path="/path/to/model.onnx",
    name="converted-model",
    quantization_mode="INT8_STANDARD",
    quantization_data="GENERAL",
    use_per_channel_quantization=True,
    htp_socs=["sm8550"],
)
```

#### Generic Conversion

Convert to any supported target:

```python
from hubai_sdk.utils.types import Target

response = client.convert.convert(
    target=Target.RVC4,  # or Target.RVC2, Target.HAILO, etc.
    path="/path/to/model.onnx",
    name="converted-model",
    quantization_mode="INT8_STANDARD",
    quantization_data="GENERAL",
    input_shape=[1, 3, 288, 512],
)
```

## 💻 CLI Usage

The SDK also provides a command-line interface:

```bash
# Login
hubai login

# List models
hubai model ls

# Get model info
hubai model info <model-id-or-slug>

# Create a model
hubai model create "my-model" --license-type MIT --tasks OBJECT_DETECTION

# Convert a model
hubai convert RVC2 --path /path/to/model.onnx --name "my-model"

# List variants
hubai variant ls

# List instances
hubai instance ls
```

For more CLI options, use the `--help` flag:

```bash
hubai --help
hubai model --help
hubai convert --help
hubai convert RVC4 --help
```

## 📚 Examples

See the `examples/` directory for more detailed usage examples:

- [examples/models.py](examples/models.py): Model management operations
- [examples/variants.py](examples/variants.py): Variant management operations
- [examples/instances.py](examples/instances.py): Instance management and
  file operations
- [examples/conversion](examples/conversion): Model conversion examples
  for different formats

## Migration from `blobconverter`

[BlobConverter](https://pypi.org/project/blobconverter/) is our
previous library for converting models to the BLOB format usable with
`RVC2` and `RVC3` devices. It is being replaced by `modelconverter`
and `HubAI SDK`, which will eventually become the supported
conversion path.

`blobconverter` is still available and can be used for conversion, but
we recommend using `HubAI SDK` for new projects. The HubAI SDK API is
similar to `blobconverter`, but there are differences in parameters
and in how conversion is performed. Hosted HubAI conversion also
replaces the older
[tools.luxonis.com](https://tools.luxonis.com/) YOLO conversion
workflow.

`blobconverter` offers separate functions for different source
frameworks, such as `from_onnx`, `from_openvino`, and `from_tf`.
These are now replaced by `convert.RVC2` or `convert.RVC3` in
`HubAI SDK`, both of which take a `path` to the source model.

The following table shows the mapping between `blobconverter`
parameters and `HubAI SDK` parameters.

| `blobconverter`    | `HubAI SDK`                              | Notes                                                                                                                                        |
| ------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`            | `path`                                   | The model file path.                                                                                                                         |
| `xml`              | `path`                                   | The XML file path. Only for conversion from OpenVINO IR                                                                                      |
| `bin`              | `opts["input_bin"]`                      | The BIN file path. Only for conversion from OpenVINO IR when it is not beside the XML file. See the [example](#conversion-from-openvino-ir). |
| `version`          | `tool_version`                           | The version of the conversion tool.                                                                                                          |
| `data_type`        | `compress_to_fp16` / `quantization_mode` | `RVC2` and `RVC3` use `compress_to_fp16`. `RVC4` uses `quantization_mode`.                                                                   |
| `shaves`           | `number_of_shaves`                       | The number of shaves to use.                                                                                                                 |
| `optimizer_params` | `mo_args`                                | The arguments to pass to the model optimizer.                                                                                                |
| `compile_params`   | `compile_tool_args`                      | The arguments to pass to the BLOB compiler.                                                                                                  |

By default, `HubAI SDK` enables `superblob`, which is only supported
on DepthAI v3. To produce the legacy RVC2 blob format, pass
`superblob=False` to `convert.RVC2`.

### Simple Conversion

**Simple ONNX conversion using `blobconverter`**

```python
import blobconverter

blob = blobconverter.from_onnx(
    model="resnet18.onnx",
)
```

**Equivalent code using `HubAI SDK`**

```python
response = client.convert.RVC2(
    path="resnet18.onnx",
)

blob = response.downloaded_path
```

### Conversion from OpenVINO IR

**`blobconverter` example**

```python
import blobconverter

blob = blobconverter.from_openvino(
    xml="resnet18.xml",
    bin="resnet18.bin",
)
```

**`HubAI SDK` example**

```python
# When the XML and BIN files are at the same location,
# only the XML needs to be specified
response = client.convert.RVC2("resnet18.xml")
blob = response.downloaded_path

# Otherwise, specify the BIN file explicitly using
# the `opts` parameter
response = client.convert.RVC2(
    path="resnet18.xml",
    opts={
        "input_bin": "/other/path/resnet18.bin",
    },
)
blob = response.downloaded_path
```

### Conversion from `tflite`

> [!WARNING]
> HubAI online conversion does not support frozen PB files. Only
> TFLite files are supported.

`blobconverter`

```python
import blobconverter

blob = blobconverter.from_tf(
    frozen_pb="resnet18.tflite",
)
```

**Equivalent code using `HubAI SDK`**

```python
response = client.convert.RVC2(
    path="resnet18.tflite",
)

blob = response.downloaded_path
```

### Advanced Parameters

**`blobconverter.from_onnx` with advanced parameters**

```python
import blobconverter

blob = blobconverter.from_onnx(
    model="resnet18.onnx",
    data_type="FP16",
    version="2021.4",
    shaves=6,
    optimizer_params=[
        "--mean_values=[127.5,127.5,127.5]",
        "--scale_values=[255,255,255]",
    ],
    compile_params=["-ip U8"],
)
```

**Equivalent code using `HubAI SDK`**

```python
response = client.convert.RVC2(
    path="resnet18.onnx",
    compress_to_fp16=True,
    tool_version="2021.4.0",
    number_of_shaves=6,
    mo_args=[
        "mean_values=[127.5,127.5,127.5]",
        "scale_values=[255,255,255]",
    ],
    compile_tool_args=["-ip", "U8"],
)

blob = response.downloaded_path
```

### `Caffe` Conversion

Conversion from the `Caffe` framework is not supported.

## 📄 Available Parameters

See [docs/available_parameters.md](docs/available_parameters.md) for
the full conversion parameter reference.

## 🔨 Development

### Setup Development Environment

```bash
git clone https://github.com/luxonis/hubai-sdk.git
cd hubai-sdk
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## 💬 Support

- **Issues**: [GitHub Issues](https://github.com/luxonis/hubai-sdk/issues)
- **Email**: support@luxonis.com
- **Documentation**: [HubAI Platform](https://docs.luxonis.com)

## 🔗 Links

- **Repository**: [https://github.com/luxonis/hubai-sdk](https://github.com/luxonis/hubai-sdk)
- **HubAI Platform**: [https://hub.luxonis.com](https://hub.luxonis.com)
- **Luxonis**: [https://luxonis.com](https://luxonis.com)
