# The Hub AI workflow

## Overview

Hub AI turns model development into a repeatable loop: collect representative data, annotate and validate it, train and evaluate a
model, deploy the best version, then use production observations to improve the next version.

> **Note**
> The loop is iterative rather than strictly linear. You can return to data collection, annotation, training, or evaluation whenever the evidence shows that the model needs different examples or labels.

Pipeline nodes:
- Collect or upload
- Annotate and version
- Train and evaluate
- Model version
- Convert and deploy
- Production Snaps

Pipeline connections:
- Collect or upload -> Annotate and version
- Annotate and version -> Train and evaluate
- Train and evaluate -> Model version
- Model version -> Convert and deploy
- Convert and deploy -> Production Snaps
- Production Snaps -> Collect or upload

## 1. Collect samples

Start with images that represent the conditions where the model will run. Upload an existing annotated archive, an image
collection, or add individual [Snaps](https://docs.luxonis.com/cloud/features/event-storage/snaps.md).

Define the dataset tasks, task names, and classes before import so Hub can map annotations correctly. Use [Create, Upload &
Export](https://docs.luxonis.com/cloud/hubai/training/datasets/upload.md) for each ingestion path and its parser requirements.

## 2. Annotate and review

Label samples manually, accelerate compatible tasks with [Smart
Annotations](https://docs.luxonis.com/cloud/hubai/training/datasets/annotate.md), or use a checkpoint from an earlier Hub training
run to [pre-annotate a batch](https://docs.luxonis.com/cloud/hubai/training/datasets/annotate.md). Machine-generated labels return
as Pre-annotated and should be reviewed.

Annotation statuses can express the team's review process. Move approved samples to Completed, because completed samples determine
the split sizes used by dataset health and run validation. See
[Annotate](https://docs.luxonis.com/cloud/hubai/training/datasets/annotate.md).

## 3. Check health and freeze the input

Review dataset size, split distribution, and class distribution. Use train data to update weights, validation data to select the
best checkpoint, and held-out test data for the final comparison. Health is an advisory signal: investigate warnings in the
context of the deployment problem rather than treating the label as a guarantee.

For reproducible experiments, enable Version Dataset on the training run. The read-only snapshot records the run's data state and
can optionally include only samples matching selected tags. Hub reuses the latest version when the source and tag filter have not
changed. See [Health, Splits & Versions](https://docs.luxonis.com/cloud/hubai/training/datasets/health-splits-versions.md).

## 4. Train in a project

Create a project from the dataset so the task names, types, and classes match. Add a linked model and select a compatible
LuxonisTrain architecture. A training run combines that model with a dataset input, checkpoint strategy, and compute speed.

The conservative estimate is reserved in [credits](https://docs.luxonis.com/cloud/hubai/training/credits.md), while
[Jobs](https://docs.luxonis.com/cloud/hubai/training/jobs.md) coordinates versioning, export, training, and model registration.
Follow [Training & Evaluation Runs](https://docs.luxonis.com/cloud/hubai/training/runs.md) to create and control the experiment.

## 5. Evaluate and compare

Every successful training run publishes a new linked-model version with two artifacts:

 * an ONNX [NN Archive](https://docs.luxonis.com/software-v3/ai-inference/nn-archive.md) for inference and conversion;
 * a PyTorch checkpoint for evaluation, resumed training, and pre-annotation.

Use the run's main metric to compare experiments made from equivalent dataset versions. Then inspect validation and test metrics,
loss and metric curves, per-class results, and inference images before choosing a candidate. [Training and evaluation
runs](https://docs.luxonis.com/cloud/hubai/training/runs.md) explains the signals and common curve patterns.

## 6. Promote and deploy

Add model-version tags such as `candidate` or `production` to communicate which model is best fit for your application. A tag can
move to a newer version while the version history and training-run links preserve the experiment record.

Open Deploy from the training run or convert the ONNX archive from the [Model
Registry](https://docs.luxonis.com/cloud/hubai/model-registry/concepts.md). Select the correct target platform, then reference the
resulting RVC model instance from the DepthAI pipeline or OAK App.

For production workloads, prefer an immutable model instance identifier when the application must remain pinned to a specific
compiled artifact.

## 7. Feed observations back into data

Once the model is deployed, capture difficult scenes, missed detections, and representative new environments as Snaps. Add them to
the dataset, annotate or pre-annotate them, and use tags to organize the next cohort.

Create another dataset version, run a comparable experiment, and promote the new model only when evaluation shows an improvement
that matters to the deployment. The links among dataset version, training run, model version, and model tag provide the audit
trail for that decision.