hubai_sdk.services.instances

module documentation

Manage concrete model artifacts and their files.

An instance belongs to one model variant and represents a specific artifact format, for example ONNX input or an RVC4 export. The service supports listing and creating instances, uploading source files, reading NN Archive configuration, and downloading output files.

Download behavior:: download_instance writes all files associated with an instance. If output_dir is omitted it creates a directory named after the instance slug in the current working directory. Existing destination files are reused unless force=True.

Example

from hubai_sdk.utils.types import ModelType

instance = client.instances.create_instance(
    "network",
    variant_id=variant.id,
    model_type=ModelType.ONNX,
    input_shape=[1, 3, 640, 640],
)
client.instances.upload_file("network.onnx", instance.id)

Note

Most users do not need to create and upload instances manually. The functions in hubai_sdk.services.convert coordinate these steps for a complete hosted conversion.

Function	`create_instance`	Create a model artifact beneath a variant.
Function	`create_instance_cli`	Creates a new model instance.
Function	`delete_instance`	Delete a model instance from HubAI.
Function	`delete_instance_cli`	Deletes a model instance.
Function	`download_instance`	Download every file attached to a model instance.
Function	`download_instance_cli`	Downloads files from a model instance.
Function	`get_config`	Return the NN Archive configuration of a model instance.
Function	`get_config_cli`	Returns the configuration of a model instance.
Function	`get_files`	Return metadata for files attached to a model instance.
Function	`get_files_cli`	Returns the files of a model instance.
Function	`get_instance`	Get one model instance by UUID or slug.
Function	`get_instance_info_cli`	Returns information about a model instance.
Function	`list_instances`	List model instances visible to the authenticated team.
Function	`list_instances_cli`	List the model instances in the HubAI.
Function	`upload_file`	Upload a file directly to storage for a model instance.
Function	`upload_file_cli`	Uploads a file to a model instance using async upload.
Function	`upload_quantization_zip`	Upload a custom calibration archive for an export job.
Constant	`INSTANCE_INFO_KEYS`	Undocumented
Constant	`INSTANCE_LIST_KEYS`	Undocumented
Constant	`INSTANCE_LIST_KEYS_WITH_MODEL`	Undocumented
Variable	`app`	Undocumented
Function	`_dump_for_cli`	Convert SDK response objects into JSON-serializable CLI data.
Function	`_get_instance_subresource`	Fetch a subresource for a model instance after resolving its ID.
Function	`_instance_to_cli_data`	Undocumented
Function	`_print_instance_info`	Undocumented
Function	`_print_instance_list`	Undocumented

@telemetry_operation(OperationTelemetrySpec(operation_name=OperationName.INSTANCE_CREATE, operation_group=TelemetryGroup.INSTANCES, success_event=INSTANCE_CREATED_EVENT, target_resource=TargetResource.INSTANCE, success_builder=build_instance_created_properties))

Create a model artifact beneath a variant.

Parameters
name:`str`	Human-readable instance name.
variant_id:`UUID \| str`	UUID of the model variant that owns this instance.
model_type:`ModelType`	Source or exported artifact type.
parent_id:`UUID \| str \| None`	Source instance UUID when this instance is an export.
quantization_mode:`QuantizationMode \| None`	Quantization mode for the model. Must be one of `INT8_STANDARD`, `INT8_ACCURACY_FOCUSED`, `INT8_INT16_MIXED`, `INT8_INT16_MIXED_ACCURACY_FOCUSED`, or `FP16_STANDARD`. `INT8_STANDARD` is standard INT8 quantization with calibration for optimal performance and model size. `INT8_ACCURACY_FOCUSED` is INT8 quantization with calibration that may improve accuracy without reducing performance or increasing model size, depending on the model. `INT8_INT16_MIXED` uses 8-bit weights and 16-bit activations across all layers for improved numeric stability and accuracy at the cost of performance and model size. `INT8_INT16_MIXED_ACCURACY_FOCUSED` is a mixed INT8 and INT16 calibration-based mode that prioritizes accuracy over throughput. `FP16_STANDARD` is FP16 quantization without calibration for models that require higher accuracy and numeric stability at the cost of performance and model size.
quantization_data:`QuantizationData \| None`	Quantization data for the model. This can be one of the predefined domains `DRIVING`, `FOOD`, `GENERAL`, `INDOORS`, `RANDOM`, `WAREHOUSE`, `CLIP`, `CUSTOM`, or `UNKNOWN`, or a dataset ID. For conversion helpers, pass the local `.zip` path itself instead of `CUSTOM`; the SDK normalizes that input before instance creation.
tags:`list[str] \| None`	Tags for the model instance.
input_shape:`list[int] \| None`	Input shape for the model instance.
is_deployable:`bool \| None`	Whether the model instance is deployable.
yolo_version:`YoloVersion \| None`	YOLO version for the model instance if it is a YOLO model.

Returns
`ModelInstanceResponse`	The created model instance resource.

@app.command(name='create')

Creates a new model instance.

@telemetry_operation(OperationTelemetrySpec(operation_name=OperationName.INSTANCE_DELETE, operation_group=TelemetryGroup.INSTANCES, success_event=INSTANCE_DELETED_EVENT, target_resource=TargetResource.INSTANCE, identifier_param='identifier', success_builder=build_model_identifier_properties))

def delete_instance(identifier: UUID | str): ¶

Delete a model instance from HubAI.

Parameters
identifier:`UUID \| str`	The model instance ID or slug.

@app.command(name='delete')

def delete_instance_cli(identifier: UUID | str): ¶

Deletes a model instance.

@telemetry_operation(OperationTelemetrySpec(operation_name=OperationName.INSTANCE_DOWNLOAD, operation_group=TelemetryGroup.INSTANCES, success_event=INSTANCE_DOWNLOAD_COMPLETED_EVENT, target_resource=TargetResource.INSTANCE, identifier_param='identifier', success_builder=build_instance_downloaded_properties))

def download_instance(identifier: UUID | str, output_dir: str | None = None, force: bool = False) -> Path: ¶

Download every file attached to a model instance.

Parameters
identifier:`UUID \| str`	The model instance ID or slug.
output_dir:`str \| None`	Directory path to save the downloaded files. If not specified, the downloader creates a directory named after the model instance slug under the current working directory.
force:`bool`	Whether to force download the files even if they already exist.

Returns
`Path`	Path to the downloaded file. When the instance has multiple files, this is the last file processed.

Raises
`ResourceNotFoundError`	If `identifier` cannot be resolved.
`HubApiError`	If the instance has no files or a download fails.

@app.command(name='download')

def download_instance_cli(identifier: UUID | str, output_dir: str | None = None, force: bool = False): ¶

Downloads files from a model instance.

@telemetry_operation(OperationTelemetrySpec(operation_name=OperationName.INSTANCE_CONFIG_GET, operation_group=TelemetryGroup.INSTANCES, success_event=INSTANCE_CONFIG_RETRIEVED_EVENT, target_resource=TargetResource.INSTANCE, identifier_param='identifier', success_builder=build_model_identifier_properties))

def get_config(identifier: UUID | str) -> ArchiveConfigurationResponse: ¶

Return the NN Archive configuration of a model instance.

Parameters
identifier:`UUID \| str`	The model instance ID or slug.

Returns
`ArchiveConfigurationResponse`	The NN archive configuration for the model instance.

@app.command(name='config')

def get_config_cli(identifier: UUID | str): ¶

Returns the configuration of a model instance.

@telemetry_operation(OperationTelemetrySpec(operation_name=OperationName.INSTANCE_FILES_LIST, operation_group=TelemetryGroup.INSTANCES, success_event=INSTANCE_FILES_LISTED_EVENT, target_resource=TargetResource.INSTANCE, identifier_param='identifier', success_builder=build_instance_files_listed_properties))

def get_files(identifier: UUID | str) -> list[ModelInstanceFileResponse]: ¶

Return metadata for files attached to a model instance.

Parameters
identifier:`UUID \| str`	The model instance ID or slug.

Returns
`list[ModelInstanceFileResponse]`	File metadata for the model instance.

@app.command(name='files')

def get_files_cli(identifier: UUID | str): ¶

Returns the files of a model instance.

@telemetry_operation(OperationTelemetrySpec(operation_name=OperationName.INSTANCE_GET, operation_group=TelemetryGroup.INSTANCES, success_event=INSTANCE_RETRIEVED_EVENT, target_resource=TargetResource.INSTANCE, identifier_param='identifier', success_builder=build_model_identifier_properties))

def get_instance(identifier: UUID | str) -> ModelInstanceResponse: ¶

Get one model instance by UUID or slug.

Parameters
identifier:`UUID \| str`	The model instance ID or slug.

Returns
`ModelInstanceResponse`	The resolved model instance resource.

@app.command(name='info')

def get_instance_info_cli(identifier: UUID | str): ¶

Returns information about a model instance.

@telemetry_operation(OperationTelemetrySpec(operation_name=OperationName.INSTANCES_LIST, operation_group=TelemetryGroup.INSTANCES, success_event=INSTANCES_LISTED_EVENT, target_resource=TargetResource.INSTANCE, success_builder=build_instances_listed_properties))

List model instances visible to the authenticated team.

Parameters
platforms:`list[ModelType] \| None`	Filter the listed model instances by platform.
search:`str \| None`	Search the listed model instances by a free-text query.
model_id:`UUID \| str \| None`	Filter the listed model instances by model ID.
variant_id:`UUID \| str \| None`	Filter the listed model instances by variant ID.
model_type:`ModelType \| None`	Filter the listed model instances by model type.
parent_id:`UUID \| str \| None`	Filter the listed model instances by parent ID.
model_class:`ModelClass \| None`	Filter the listed model instances by model class.
name:`str \| None`	Filter the listed model instances by name.
hash:`str \| None`	Filter the listed model instances by hash.
status:`Status \| None`	Filter the listed model instances by status.
is_public:`bool \| None`	Filter the listed model instances by visibility.
compression_level:`Literal[0, 1, 2, 3, 4, 5] \| None`	Filter the listed model instances by compression level. Only relevant for Hailo models.
optimization_level:`Literal[-100, 0, 1, 2, 3, 4] \| None`	Filter the listed model instances by optimization level. Only relevant for Hailo models.
include_model_name:`bool`	If `True`, include the model name and model variant name in the response. Otherwise, `ModelInstanceResponse.model_name` and `ModelInstanceResponse.model_variant_name` are `None`. Enabling this performs two additional API requests per result.
limit:`int`	Maximum number of model instances to return.
sort:`str`	Field to sort the model instances by. It should be a field name from `ModelInstanceResponse`, such as `"name"`, `"id"`, or `"updated"`.
order:`Order`	Sort order. Must be `"asc"` or `"desc"`.

Returns
`list[ModelInstanceResponse]`	A list of matching model instance resources.

@app.command(name='ls')

List the model instances in the HubAI.

@telemetry_operation(OperationTelemetrySpec(operation_name=OperationName.INSTANCE_UPLOAD, operation_group=TelemetryGroup.INSTANCES, success_event=INSTANCE_FILE_UPLOADED_EVENT, target_resource=TargetResource.INSTANCE, identifier_param='identifier', success_builder=build_instance_uploaded_properties))

def upload_file(file_path: str, identifier: UUID | str): ¶

Upload a file directly to storage for a model instance.

This function initiates an async upload by first obtaining a signed upload policy from the server, then uploading the file directly to cloud storage.

Parameters
file_path:`str`	Path to the file to upload.
identifier:`UUID \| str`	The model instance ID or slug.

Raises
`FileNotFoundError`	If `file_path` does not exist.
`ResourceNotFoundError`	If `identifier` cannot be resolved.
`HubApiError`	If the signed upload or its asynchronous job fails.

@app.command(name='upload')

def upload_file_cli(file_path: str, identifier: UUID | str): ¶

Uploads a file to a model instance using async upload.

def upload_quantization_zip(file_path: str, job_id: UUID | str): ¶

Upload a custom calibration archive for an export job.

Parameters
file_path:`str`	Path to a local ZIP archive containing calibration inputs.
job_id:`UUID \| str`	Export job UUID returned by HubAI.

Raises
`FileNotFoundError`	If `file_path` does not exist.
`InputError`	If the file does not have a `.zip` extension.
`HubApiError`	If HubAI cannot issue or complete the upload.

INSTANCE_INFO_KEYS: list[str] = ¶

Undocumented

Value

['model_name',
 'model_variant_name',
 'name',
 'slug',
 'id',
 'model_version_id',
 'model_id',
...

INSTANCE_LIST_KEYS: list[str] = ¶

Undocumented

Value

['slug', 'id', 'model_type', 'is_nn_archive', 'model_precision_type']

INSTANCE_LIST_KEYS_WITH_MODEL: list[str] = ¶

Undocumented

Value

['model_name',
 'model_variant_name',
 'slug',
 'id',
 'model_type',
 'is_nn_archive',
 'model_precision_type']

app = ¶

Undocumented

def _dump_for_cli(resource: object) -> object: ¶

Convert SDK response objects into JSON-serializable CLI data.

def _get_instance_subresource(identifier: UUID | str, subpath: str) -> dict[str, object] | list[dict[str, object]]: ¶

Fetch a subresource for a model instance after resolving its ID.

def _instance_to_cli_data(instance: ModelInstanceResponse) -> dict[str, object]: ¶

Undocumented

def _print_instance_info(instance: ModelInstanceResponse): ¶

Undocumented

def _print_instance_list(instances: list[ModelInstanceResponse], include_model_name: bool, field: list[str] | None = None): ¶

Undocumented