Skip to content
BranchesTags

Repository files navigation

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 instead.

For complete SDK, CLI, and conversion parameter documentation, see the HubAI SDK API reference.

✨ 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:

pip install hubai-sdk

Or install from source:

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

📋 Requirements

🔐 Authentication

Get Your API Key

  1. Visit HubAI Team API Key Settings
  2. Generate or copy your API key

Set API Key

You can authenticate in several ways:

Option 1: Environment Variable

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

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

from hubai_sdk import HubAIClient

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

🚀 Quick Start

Python SDK Usage

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 resource identifiers

All operations that accept an identifier accept a resource ID or its raw slug. They also accept the following human-readable resource paths:

Resource Resource paths
Model <team>/<model>
Variant <model>:<variant>, <team>/<model>:<variant>, <model>:<variant>:<version>, <team>/<model>:<variant>:<version>
Instance <model>:<variant>:<instance-hash>, <team>/<model>:<variant>:<instance-hash>

Here, instance-hash is the instance response's hash_short value. A three-part path identifies a model version for variant operations and an instance for instance operations.

For example:

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

When several versions have the same variant slug, include the version segment to select one exactly, for example luxonis/yolov6-nano:r2-coco-512x384:1.1.0.

🤖 Models Service (client.models)

Manage ML models in HubAI.

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

# Get model by ID, raw slug, or resource path
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.

# Assume `model` is a `ModelResponse`.

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

# Get variant by ID, raw slug, or resource path
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).

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 an instance by its ID or raw instance slug
downloaded_path = client.instances.download_instance(instance.id)

# Download one exact instance by its resource path
downloaded_path = client.instances.download_instance(
    "yolov6-nano:r2-coco-512x384:fb1429e",
)

# Or select an instance beneath a variant by its type
downloaded_path = client.instances.download_instance(
    "luxonis/yolov6-nano:r2-coco-512x384",
    model_type=ModelType.ONNX,
)

# 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:

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:

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:

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:

# 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

# Download a typed instance from a model variant
hubai instance download luxonis/yolov6-nano:r2-coco-512x384 --model-type ONNX

# Download one exact instance by its resource path
hubai instance download yolov6-nano:r2-coco-512x384:fb1429e

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

hubai --help
hubai model --help
hubai convert --help
hubai convert RVC4 --help

📚 Examples

See the examples/ directory for more detailed usage examples:

Migration from blobconverter

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 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.
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

import blobconverter

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

Equivalent code using HubAI SDK

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

blob = response.downloaded_path

Conversion from OpenVINO IR

blobconverter example

import blobconverter

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

HubAI SDK example

# 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

import blobconverter

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

Equivalent code using HubAI SDK

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

blob = response.downloaded_path

Advanced Parameters

blobconverter.from_onnx with advanced parameters

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

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.

🔨 Development

Setup Development Environment

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

🔗 Links

About

Python SDK & CLI for interacting with Luxonis HubAI - a platform for managing, converting, and deploying machine learning models to Luxonis OAK cameras.

Resources

Readme
Apache-2.0 license
Activity
Custom properties

Stars

5 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages