Skip to content
/ hubai-sdk Public

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

License

Apache-2.0 license
2 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

luxonis/hubai-sdk

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.

✨ 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 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 will open a browser to generate a new API key and prompt you to enter it, which will be securely stored. Use hubai login --relogin to relogin with different API key or hubai logout to logout.

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 Slugs from HubAI

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

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

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

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

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

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",
    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.RVC2,  # or Target.RVC4, Target.HAILO, etc.
    path="/path/to/model.onnx",
    name="converted-model",
    quantization_mode="INT8_STANDARD",
    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

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

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

📚 Examples

See the examples/ directory for more detailed usage examples:

  • examples/models.py: Model management operations
  • examples/variants.py: Variant management operations
  • examples/instances.py: Instance management and file operations
  • examples/conversion/: Model conversion examples for different formats

Migration from blobconverter

BlobConverter is our previous library for converting models to the BLOB format usable with RVC2 and RVC3 devices. This library is being replaced by modelconverter and HubAI SDK, which eventually become the only supported way of converting models in the future.

blobconverter is still available and can be used for conversion, but we recommend using HubAI SDK for new projects. The API of HUBAI SDK is similar to that of blobconverter, but there are some differences in the parameters and the way the conversion is done.

blobconverter offers several functions for converting models from different frameworks, such as from_onnx, from_openvino, and from_tf. These functions are now replaced by the convert.RVC2 (or convert.RVC3) function in HubAI SDK, which takes a single argument path that specifies the path to the model file.

The following table shows the mapping between the parameters of blobconverter and HUBAI SDK. The parameters are grouped by their purpose. The first column shows the parameters of blobconverter, the second column shows the equivalent parameters in HubAI SDK, and the third column contains additional notes.

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. See the example.
version tool_version The version of the conversion tool.
data_type quantization_mode The quantization mode of the model.
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 has superblob enabled which is only supported on DepthAI v3. If you want to convert a model to legacy RVC2 format (blob), you can pass superblob=False to the convert.RVC2 function.

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, the BIN file can be specified using
# the `opts` parameter
response = client.convert.RVC2(
    path="resnet18.xml",
    opts={
        "input_bin": "resnet18.bin",
    }
)
blob = response.downloaded_path

Conversion from tflite

Warning

HubAI online conversion does not support conversion from 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",
    quantization_mode="FP16_STANDARD",
    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.

📄 All Available Parameters

See the All available parameters file for all available parameters during conversion.

🔨 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

License

Apache-2.0 license
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 5

v0.2.0 Latest
Jan 22, 2026
+ 4 releases

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages