# Models SDK

## Overview

The [hubai-sdk](https://github.com/luxonis/hubai-sdk) package is a Python library for interacting with the [AI &
Models](https://docs.luxonis.com/cloud/hubai.md) area of Luxonis Hub programmatically. It enables automation of model management
and conversion workflows directly from your Python code or command line.

Key Features:

 * Programmatic access to models, variants, and instances
 * Automated model conversion to RVC2, RVC3, RVC4, and Hailo formats
 * Command-line interface for all operations
 * Type-safe Python API with full type hints
 * Support for both Python scripts and CLI workflows

## Installation

The package is hosted on PyPI so it can be installed with pip:

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

## Quick Start

In order to use this SDK, you first need to obtain an API key from [Hub](https://hub.luxonis.com/ai). You can do this by signing
up for a free account and generating an API key in the settings.

```python
import os
from hubai_sdk import HubAIClient

client = HubAIClient(api_key=os.getenv("HUBAI_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 RVC4 format (for OAK4 devices)
response = client.convert.RVC4(
    path="/path/to/your/nn_archive.tar.xz",
    name="my-converted-model",
    target_precision="INT8",
    quantization_data="GENERAL",
)

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

All the commands can also be run from the command line using the hubai command.

```bash
# Login first
hubai login

# List models
hubai model ls

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

# Convert model to RVC4 format
hubai convert rvc4 <path-to-nn-archive.tar.xz> --name my-converted-model --target-precision INT8 --quantization-data GENERAL
```

## Installation

The package works on Python 3.10 and above and can be installed using pip:

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

Additionally, you can install the package from the source code:

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

## Authentication

To use this SDK, you need to create an account on [Hub](https://hub.luxonis.com) and generate an API key in your [team
settings](https://docs.luxonis.com/cloud/api/api-keys.md). Once you have the API key, you can set it as an environment variable:

## 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(
    model_id,
    license_type="Apache 2.0",
    description="Updated description"
)

# Delete a model
client.models.delete_model(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",
    target_precision="INT8",
    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",
    target_precision="INT8",
    quantization_data="GENERAL",
    yolo_input_shape=[512, 288],
    yolo_class_names=["list", "of", "class", "names"],
    yolo_version="yolov8",  # or any other YOLO version
)
```

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. The currently supported
families include YOLOv5, YOLOv6, YOLOv7, YOLOv8, YOLOv9, YOLOv10, YOLO11, YOLO12, YOLO26, YOLOE, and Gold-YOLO. 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.