# HubAI SDK

## Overview

The [hubai-sdk](https://github.com/luxonis/hubai-sdk) package provides programmatic access to the [AI &
Models](https://docs.luxonis.com/cloud/hubai.md) area of Luxonis Hub. Use it to manage models, variants, and instances, or to
trigger online conversion from Python or the command line.

Key capabilities:

 * Manage models, variants, and instances in Hub AI
 * Run online conversion for RVC2, RVC3, RVC4, and Hailo targets
 * Use the same workflows from Python scripts or the hubai CLI
 * Access advanced conversion options that are not exposed in the Hub UI

> If you only need the conversion workflow, see the
> [HubAI online conversion guide](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/online/hubai.md)
> .

## Installation

The package works on Python 3.10 and above.

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

You can also install it from source:

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

## Authentication

Create an API key in your [team settings](https://docs.luxonis.com/cloud/api/api-keys.md), then expose it as an environment
variable:

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

Initialize the client in Python:

```python
import os

from hubai_sdk import HubAIClient

client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))
```

All SDK workflows are also available through the hubai CLI. Start by logging in:

```bash
hubai login
```

## Quick Start

The example below shows a minimal end-to-end flow: list a few models and run an online conversion.

```python
models = client.models.list_models(limit=5)
print(f"Found {len(models)} models")

response = client.convert.RVC4(
    path="path/to/model.onnx",
    name="my-converted-model",
)

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

## Model Management

[Model](https://docs.luxonis.com/cloud/hubai/model-registry/concepts.md) is the basic element of the AI & Models area and can be
managed programmatically using the HubAIClient.models namespace. You can list the models, retrieve information about a specific
model, create a new model, update an existing model, and delete a model.

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

# Get model Info
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 an existing model (pass only the fields you want to update)
updated_model = client.models.update_model(
    new_model.id,
    license_type="Apache 2.0",
    description="Updated description"
)

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

You have full type hints for the returned objects and you can use them to access the model properties.

## Variant Management

[Variant](https://docs.luxonis.com/cloud/hubai/model-registry/concepts.md) is a specific version of a model, typically
distinguished by input resolution (e.g., 224x224), dataset used for training (e.g., COCO), or some smaller variation in model
architecture.

You can list the variants, retrieve information about a specific variant, create a new variant, and delete a variant.

```python
# Listing the variants
variants = client.variants.list_variants(model_id="model-id")

# Get variant info
variant = client.variants.get_variant("variant-id")

new_variant = client.variants.create_variant(
    name="my-variant",
    model_id="model-id",
    variant_version="1.0.0",
    description="My first variant."
)

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

### New Verison of the Variant

You can also create a new version of the variant. This is helpful if you have newer weights for the same model. New version can be
created by providing the same variant name, the same model id and a new version number.

```python
variant = client.variants.get_variant("variant-id")

new_version_of_variant = client.variants.create_variant(
    name=variant.name,
    model_id=variant.model_id,
    variant_version="new-version-number",
)
```

## Instance Management

[Instance](https://docs.luxonis.com/cloud/hubai/model-registry/concepts.md) is a compiled, platform-targeted version of a Variant
— the actual artifact deployed to hardware. For more information about the conversion to a platform-specific instance, see the
[Conversion](https://docs.luxonis.com/cloud/hubai/model-registry/detailed-conversion.md) guide.

You can list the instances, retrieve information about a specific instance, create a new instance, download the instance, retrieve
the files and the config of the instance, upload the file to an instance, and delete an instance.

```python
# Listing the instances
instances = client.instances.list_instances(model_id="model-id", variant_id="variant-id")

# Get instance info
instance = client.instances.get_instance("instance-id")

# Download the instance
downloaded_path = client.instances.download_instance("instance-id", output_dir="/path/to/output/directory")

# Create a new instance
from hubai_sdk.utils.types import ModelType

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

# Retrieve the config of the instance
config = client.instances.get_config("instance-id")

# Retrieve the files of the instance
files = client.instances.get_files("instance-id")

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

# Delete an instance
client.instances.delete_instance("instance-id")
```

## Conversion

You can convert models to different formats using the HubAIClient.convert namespace.

```python
# Convert a model to RVC4 format
response = client.convert.RVC4(
    path="/path/to/your/nn_archive.tar.xz",
    name="my-converted-model",
    quantization_mode="INT8_STANDARD",
    quantization_data="GENERAL",
)

downloaded_path = response.downloaded_path
instance = response.instance
```

This simple example shows how to convert a model to RVC4 format in INT8 precision using GENERAL quantization data. It will also
create a model with name my-converted-model. When conversion is finished, the converted model is downloaded to the downloaded_path
and the Model Instance is returned in the instance variable.

```python
# Convert YOLO model to RVC4 format
response = client.convert.RVC4(
    path="path/to/your/yolo-model.pt",
    name="my-converted-yolo-model",
    quantization_mode="INT8_STANDARD",
    quantization_data="GENERAL",
    yolo_input_shape=[512, 288],
    yolo_class_names=["list", "of", "class", "names"],
    yolo_version="yolov8",  # optional override
)
```

The example above demonstrates how to convert a YOLO model to the RVC4 format. You can directly provide the path to the model's
.pt weights file. The input shape of the model must be specified, and you can optionally include the class names. Supplying the
class names is recommended, otherwise, they will be automatically retrieved during the conversion process. You do not need to set
yolo_version explicitly. If it is omitted, the backend attempts to detect the version automatically from the PyTorch model file,
but the file still needs to come from one of the supported YOLO versions. The current explicit yolo_version values exposed by the
SDK are yolov5, yolov6r1, yolov6r3, yolov6r4, yolov7, yolov8, yolov9, yolov10, yolov11, yolov12, yolov26, and goldyolo. For the
exact set of supported YOLO families, variants, and current limitations, see the upstream [supported models
table](https://github.com/luxonis/tools?tab=readme-ov-file#-supported-models).

For more information about online conversion, please refer to the [Hub Online
Conversion](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/online/hubai.md) guide.