# CLI

Python API: `luxonis_train.__main__`

The `luxonis_train` command line interface.

The training, evaluation, export, and annotation commands build a
[LuxonisModel](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
from a config and call one of its methods. `inspect` only reads the loaders of the model. `--model` and `--variant` select a
packaged config, so `--config` is optional. `list-models` and `info` describe the packaged models. The `upgrade` group migrates a
config, a checkpoint, or the installation.

The global `--source` option runs one or more Python files with custom components before the command, so that the components
register.

## Functions

### annotate

```python
def annotate(opts: OptsType = None, /, *, dir_path: Path, dataset_name: str, config: str | None = None, model: str | None = None, variant: str | None = None, weights: str | None = None, bucket_storage: Literal['local', 'gcs'] = 'local', delete_local: bool = True, delete_remote: bool = True, team_id: str | None = None):
```

Annotate a directory of images into a new dataset.

The model predicts on every file directly inside `dir_path` with an image extension, such as `.jpg` or `.png`. Each head turns its
predictions into annotations. The command writes them into a `LuxonisDataset` named `dataset_name`, creates its splits when it is
not empty, and prints its summary. The images pass through a temporary dataset named `infer_from_directory`. The command deletes
an existing local dataset of that name first, and deletes the temporary one at the end. A
[DummyLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
replaces a loader that fails to initialize, so the command runs without a dataset.

Parameters

 * `opts` (`OptsType`): Config overrides as alternating key and value tokens, for example `trainer.epochs 10`.
 * `dir_path` (`Path`): Directory with the images to annotate. It must be a directory.
 * `dataset_name` (`str`): Name of the dataset to create.
 * `config` (`str | None`): Path or URL of the config file. Mutually exclusive with `model`. If omitted, the packaged config of
   `model` applies, else the config stored in the `weights` checkpoint.
 * `model` (`str | None`): Name of a packaged predefined model, for example `"detection"` or `"detection:v1"`. Run `luxonis_train
   list-models` to see the options.
 * `variant` (`str | None`): Variant of the predefined model, for example `"light"` or `"heavy"`. Defaults to the default variant
   of the model.
 * `weights` (`str | None`): Path or URL of the checkpoint to annotate with. If omitted, `model.weights` of the config applies.
 * `bucket_storage` (`Literal['local', 'gcs']`): Where the command stores the new dataset.
 * `delete_local` (`bool`): Delete an existing local dataset of the same name first. With `False`, the command adds the
   annotations to the existing dataset.
 * `delete_remote` (`bool`): Also delete the remote copy of an existing dataset of the same name.
 * `team_id` (`str | None`): Team that owns the dataset. `None` reads `LUXONISML_TEAM_ID` from the environment.

### archive

```python
def archive(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, executable: str | None = None, weights: str | None = None):
```

Pack the exported model into an NN Archive.

The archive holds the executable, its `.data` file when one exists, and a config with the inputs, the outputs, the preprocessing,
and the heads. It goes to the `archive` directory of the run save directory. The command uploads the archive to
`archiver.upload_url` when that is set, and to the run when `archiver.upload_to_run` is set. A
[DummyLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
replaces a loader that fails to initialize, so the command runs without a dataset.

Parameters

 * `opts` (`OptsType`): Config overrides as alternating key and value tokens, for example `trainer.epochs 10`.
 * `config` (`str | None`): Path or URL of the config file. Mutually exclusive with `model`. If omitted, the packaged config of
   `model` applies, else the config stored in the `weights` checkpoint.
 * `model` (`str | None`): Name of a packaged predefined model, for example `"detection"` or `"detection:v1"`. Run `luxonis_train
   list-models` to see the options.
 * `variant` (`str | None`): Variant of the predefined model, for example `"light"` or `"heavy"`. Defaults to the default variant
   of the model.
 * `executable` (`str | None`): Path to the exported ONNX model. Another format stops the command with a `NotImplementedError`. If
   omitted, the command exports the model to ONNX first.
 * `weights` (`str | None`): Path or URL of the checkpoint to archive. If omitted, `model.weights` of the config applies.

### checkpoint

```python
def checkpoint(opts: OptsType = None, /, *, path: Annotated[Path, Parameter(validator=validators.Path(exists=True))], output: Path | None = None, config: Path | None = None):
```

Upgrade a checkpoint file to the current format.

The command builds the model from `config`, or from the config stored in the checkpoint, and loads the checkpoint into it. Then it
runs the validation loop once to attach the model to the trainer. It saves the checkpoint again with the current config, execution
order, and dataset metadata. A checkpoint without a stored config needs `config`. Without a dataset, a
[DummyLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
stands in for the validation loop. The command is also named `ckpt`.

Parameters

 * `opts` (`OptsType`): Config overrides as alternating key and value tokens, for example `trainer.epochs 10`.
 * `path` (`Annotated[Path, Parameter(validator=validators.Path(exists=True))]`): Path to the checkpoint. It must exist.
 * `output` (`Path | None`): Where to write the upgraded checkpoint. If omitted, the command overwrites `path`.
 * `config` (`Path | None`): Config file to build the model from. If omitted, the config stored in the checkpoint applies.

### config

```python
def config(config: Annotated[Path, Parameter(validator=validators.Path(exists=True)), Parameter(validator=validators.Path(ext=set(['yaml', 'yml', 'json'])))], output: Annotated[Path | None, Parameter(validator=validators.Path(ext=set(['yaml', 'yml', 'json'])))] = None):
```

Upgrade a config file to the current schema.

The command reads the file as JSON when its suffix is `.json` and as YAML otherwise. It applies the migration steps of
[upgrade_config](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/upgrade.md)
and writes the result in the format of the output suffix. When the file is already current, the command writes it back without
migration. It drops a deprecated `config_version` field in both cases.

Parameters

 * `config` (`Annotated[Path, Parameter(validator=validators.Path(exists=True)),
   Parameter(validator=validators.Path(ext=set(['yaml', 'yml', 'json'])))]`): Path to the config file to upgrade. It must exist
   and end with `.yaml`, `.yml`, or `.json`.
 * `output` (`Annotated[Path | None, Parameter(validator=validators.Path(ext=set(['yaml', 'yml', 'json'])))]`): Where to write the
   upgraded config. It must end with `.yaml`, `.yml`, or `.json`. If omitted, the command overwrites `config`.

### convert

```python
def convert(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, save_dir: str | None = None, weights: str | None = None):
```

Export, archive, and convert the model for a target platform.

The command exports the model to ONNX, packs it into an NN Archive, and then runs the conversions the config activates:

 * `exporter.blobconverter.active`: a `.blob` for RVC2 through `blobconverter`, which is deprecated.
 * `exporter.hubai.active`: an NN Archive for `exporter.hubai.platform` (`rvc2`, `rvc3`, or `rvc4`) through the HubAI SDK.

The command skips a conversion whose package is not installed and logs it. A
[DummyLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
replaces a loader that fails to initialize, so the command runs without a dataset.

Parameters

 * `opts` (`OptsType`): Config overrides as alternating key and value tokens, for example `trainer.epochs 10`.
 * `config` (`str | None`): Path or URL of the config file. Mutually exclusive with `model`. If omitted, the packaged config of
   `model` applies, else the config stored in the `weights` checkpoint.
 * `model` (`str | None`): Name of a packaged predefined model, for example `"detection"` or `"detection:v1"`. Run `luxonis_train
   list-models` to see the options.
 * `variant` (`str | None`): Variant of the predefined model, for example `"light"` or `"heavy"`. Defaults to the default variant
   of the model.
 * `save_dir` (`str | None`): Directory for every output. If omitted, the outputs go under the run save directory.
 * `weights` (`str | None`): Path or URL of the checkpoint to convert. If omitted, `model.weights` of the config applies.

### create_model

```python
def create_model(config: PathType | Params | None = None, opts: list[str] | None = None, weights: PathType | None = None, allow_empty_dataset: bool = False, *, model: str | None = None, variant: str | None = None) -> LuxonisModel:
```

Build the model that a CLI command operates on.

The CLI imports `luxonis_train` without its submodules, so that it starts fast. This function reloads the package, which runs the
full imports, and then builds a
[LuxonisModel](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md).

Parameters

 * `config` (`PathType | Params | None`): Path or URL of the config file, or the config as a dictionary. With `None`, the packaged
   config of `model` applies, else the config stored in the `weights` checkpoint. Without those, `opts` alone builds the config
   from the defaults, and
   [Config.get_config](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md)
   raises `ValueError` when `opts` is `None` too.
 * `opts` (`list[str] | None`): Config overrides as alternating key and value tokens, for example `["trainer.epochs", "10"]`.
 * `weights` (`PathType | None`): Path or URL of a checkpoint. Its dataset metadata applies, and its weights load as soon as the
   model is built.
 * `allow_empty_dataset` (`bool`): When `True`, a
   [DummyLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
   replaces a loader that fails to initialize, so the model builds without a dataset.
 * `model` (`str | None`): Name of a packaged predefined model, with an optional version suffix such as `"detection:v1"`. Mutually
   exclusive with `config`.
 * `variant` (`str | None`): Variant of the packaged model. Requires `model`.

Returns

 * `LuxonisModel`: The model, with its loaders and its trainer built.

### export

```python
def export(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, save_path: str | None = None, weights: str | None = None, ckpt_only: bool = False):
```

Export the model to ONNX.

The command writes `<name>.onnx`. For a model with one input, it also writes a `<name>.yaml` config for `modelconverter` next to
it. `<name>` is `exporter.name` or `model.name`. With `--ckpt-only`, the command writes only `<name>.ckpt`. It saves the
checkpoint again with the current config, execution order, and dataset metadata, which refreshes an older checkpoint. Without
`--ckpt-only`, the command uploads the files to the run when `exporter.upload_to_run` is set, and to `exporter.upload_url` when
that is set. A
[DummyLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
replaces a loader that fails to initialize, so the command runs without a dataset.

Parameters

 * `opts` (`OptsType`): Config overrides as alternating key and value tokens, for example `trainer.epochs 10`.
 * `config` (`str | None`): Path or URL of the config file. Mutually exclusive with `model`. If omitted, the packaged config of
   `model` applies, else the config stored in the `weights` checkpoint.
 * `model` (`str | None`): Name of a packaged predefined model, for example `"detection"` or `"detection:v1"`. Run `luxonis_train
   list-models` to see the options.
 * `variant` (`str | None`): Variant of the predefined model, for example `"light"` or `"heavy"`. Defaults to the default variant
   of the model.
 * `save_path` (`str | None`): Directory for the exported files, or a file path whose stem names them. If omitted, the files go to
   the `export` directory of the run save directory.
 * `weights` (`str | None`): Path or URL of the checkpoint to export. If omitted, `model.weights` of the config applies.
 * `ckpt_only` (`bool`): When `True`, write only the `.ckpt` file.

### infer

```python
def infer(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, view: Literal['train', 'val', 'test'] = 'val', save_dir: Path | None = None, source_path: str | None = None, weights: str | None = None):
```

Run inference and show or save the visualizations.

Without `source_path`, the model runs over the dataset view. With it, the model runs over one image, over every image of a
directory, or over every frame of a video. Without `save_dir`, each visualizer opens a window named `<node>/<visualizer>`, and `q`
or `Esc` stops the run. An image or a directory passes through a temporary dataset named `infer_from_directory`. The command
deletes an existing local dataset of that name first, and deletes the temporary one at the end. A
[DummyLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
replaces a loader that fails to initialize, so an image or a directory source runs without a dataset. A video source needs a real
validation loader, because each frame passes through its `augment_test_image` method. A
[DummyLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
does not implement that method.

Parameters

 * `opts` (`OptsType`): Config overrides as alternating key and value tokens, for example `trainer.epochs 10`.
 * `config` (`str | None`): Path or URL of the config file. Mutually exclusive with `model`. If omitted, the packaged config of
   `model` applies, else the config stored in the `weights` checkpoint.
 * `model` (`str | None`): Name of a packaged predefined model, for example `"detection"` or `"detection:v1"`. Run `luxonis_train
   list-models` to see the options.
 * `variant` (`str | None`): Variant of the predefined model, for example `"light"` or `"heavy"`. Defaults to the default variant
   of the model.
 * `view` (`Literal['train', 'val', 'test']`): The dataset view to use when `source_path` is omitted.
 * `save_dir` (`Path | None`): Directory for the visualizations, as `.png` images or as `.mp4` videos. The command creates it when
   it is missing.
 * `source_path` (`str | None`): Path to an image file, to a directory of images, or to a video file. A directory contributes the
   files directly inside it with an image extension, such as `.jpg` or `.png`. The extension identifies a video: `.mp4`, `.mov`,
   `.avi`, `.mkv`, or `.webm`.
 * `weights` (`str | None`): Path or URL of the checkpoint to run. If omitted, `model.weights` of the config applies.

### info

```python
def info(*, model: str, variant: str | None = None):
```

Print the documentation of a packaged predefined model.

The first panel names the model, the variant, and the registry key of the resolved model class. It shows the docstring of the
class, or a fallback sentence when the class has none. One panel per component follows. A simple model gets the backbone, the neck
when it has one, and the head. Any other model gets every node. Each panel names the node class and its variant. It shows the
docstring of the class, of its `__init__` when the class has none, or a notice when both are missing. An unknown model, variant,
or version stops the command with a `ValueError`.

Parameters

 * `model` (`str`): Name of a packaged model, with an optional version suffix, for example `"detection:v1"` or
   `"detection:latest"`.
 * `variant` (`str | None`): The variant to describe. Defaults to the default variant of the model.

### inspect

```python
def inspect(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, view: Literal['train', 'val', 'test'] = 'train', size_multiplier: Annotated[float, Parameter(['--size_multiplier', '-s'])] = 1.0, list_augmentations: bool = False):
```

Show the samples of a dataset view with their labels drawn.

A window named `Visualization` shows one sample at a time. Any key moves to the next sample, and `q` or `Esc` closes the window.
The loader does not normalize the images.

Parameters

 * `opts` (`OptsType`): Config overrides as alternating key and value tokens, for example `trainer.epochs 10`.
 * `config` (`str | None`): Path or URL of the config file. Mutually exclusive with `model`. If omitted, the packaged config of
   `model` applies, else the defaults.
 * `model` (`str | None`): Name of a packaged predefined model, for example `"detection"` or `"detection:v1"`. Run `luxonis_train
   list-models` to see the options.
 * `variant` (`str | None`): Variant of the predefined model, for example `"light"` or `"heavy"`. Defaults to the default variant
   of the model.
 * `view` (`Literal['train', 'val', 'test']`): The dataset view to inspect.
 * `size_multiplier` (`Annotated[float, Parameter(['--size_multiplier', '-s'])]`): Scale factor for the image the loader returns.
   `1.0` keeps its size. The flags are `--size_multiplier` and `-s`.
 * `list_augmentations` (`bool`): When `True`, a footer lists the augmentations applied to the sample. The footer reads
   `Augmentations: none` when the sample has no tracked augmentation. A loader that does not wrap a `luxonis_ml` loader never has
   one.

### launcher

```python
def launcher(*tokens: LauncherToken, source: LauncherSource = None):
```

Run the custom component files, then run the command.

This is the entry point of the CLI. The launcher executes each file in `source` as a module before the command runs. The custom
nodes, losses, and other components in those files then register. The launcher skips a file that does not resolve to a module.
With `--source` on the command line, `luxonis_train` imports every submodule at startup, so the files can import from it.

Parameters

 * `*tokens` (`LauncherToken`): The command and its arguments, passed on unchanged.
 * `source` (`LauncherSource`): Python files with custom components. Give `--source` once per file.

### list_models

```python
def list_models():
```

List the packaged predefined models.

The command prints a table with one row per model, or a notice when no packaged model exists. The `Variants` column marks the
default variant with `*` and shows `<default>` for a config without a variant name. The `Versions` column marks the latest version
with `*` and shows `-` when the config names no registered model class. The marked values apply when the option is omitted.

### quantize

```python
def quantize(opts: list[str] | None = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, weights: str | None = None):
```

Quantize the model with AIMET.

The `exporter.aimet` section of the config sets every option. The command evaluates the float model on the validation view. It
runs post-training quantization, calibrated on the validation images, and evaluates the result. It then runs quantization-aware
training on the train view and evaluates again. It writes the quantized ONNX and its NN Archive to the `aimet` directory of the
run save directory. The command needs a dataset and the `aimet` extra.

Parameters

 * `opts` (`list[str] | None`): Config overrides as alternating key and value tokens, for example `trainer.epochs 10`.
 * `config` (`str | None`): Path or URL of the config file. Mutually exclusive with `model`. If omitted, the packaged config of
   `model` applies, else the config stored in the `weights` checkpoint.
 * `model` (`str | None`): Name of a packaged predefined model, for example `"detection"` or `"detection:v1"`. Run `luxonis_train
   list-models` to see the options.
 * `variant` (`str | None`): Variant of the predefined model, for example `"light"` or `"heavy"`. Defaults to the default variant
   of the model.
 * `weights` (`str | None`): Path or URL of the checkpoint to quantize. If omitted, `model.weights` of the config applies.

### test

```python
def test(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, view: Literal['train', 'val', 'test'] = 'test', weights: str | None = None, debug: bool = False):
```

Evaluate the model on a dataset view.

The command runs the test loop of the trainer on `view` and finalizes the tracked run.

Parameters

 * `opts` (`OptsType`): Config overrides as alternating key and value tokens, for example `trainer.epochs 10`.
 * `config` (`str | None`): Path or URL of the config file. Mutually exclusive with `model`. If omitted, the packaged config of
   `model` applies, else the config stored in the `weights` checkpoint.
 * `model` (`str | None`): Name of a packaged predefined model, for example `"detection"` or `"detection:v1"`. Run `luxonis_train
   list-models` to see the options.
 * `variant` (`str | None`): Variant of the predefined model, for example `"light"` or `"heavy"`. Defaults to the default variant
   of the model.
 * `view` (`Literal['train', 'val', 'test']`): The dataset view to evaluate.
 * `weights` (`str | None`): Path or URL of the checkpoint to evaluate. If omitted, `model.weights` of the config applies.
 * `debug` (`bool`): When `True`, a
   [DummyLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
   replaces a loader that fails to initialize, so the model builds without a valid dataset.

### train

```python
def train(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, weights: str | None = None, debug: bool = False):
```

Train the model.

The run writes its log, its config, and its checkpoints to the run save directory under `tracker.save_directory`.

Parameters

 * `opts` (`OptsType`): Config overrides as alternating key and value tokens, for example `trainer.epochs 10`.
 * `config` (`str | None`): Path or URL of the config file. Mutually exclusive with `model`. If omitted, the packaged config of
   `model` applies, else the config stored in the `weights` checkpoint.
 * `model` (`str | None`): Name of a packaged predefined model, for example `"detection"` or `"detection:v1"`. Run `luxonis_train
   list-models` to see the options.
 * `variant` (`str | None`): Variant of the predefined model, for example `"light"` or `"heavy"`. Defaults to the default variant
   of the model.
 * `weights` (`str | None`): Path or URL of a checkpoint. With `trainer.resume_training` set in the config, the run continues from
   it with its optimizer, its scheduler, and its epoch count. Otherwise only the weights load.
 * `debug` (`bool`): When `True`, a
   [DummyLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
   replaces a loader that fails to initialize, so the model builds without a valid dataset.

### tune

```python
def tune(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, weights: str | None = None, debug: bool = False):
```

Search the hyperparameters with Optuna.

The `tuner` section of the config defines the study. Each trial trains the model with sampled values. The trials go to
`tuner_study.csv` in the run save directory, and the best parameters go to the parent tracker of the study.

Parameters

 * `opts` (`OptsType`): Config overrides as alternating key and value tokens, for example `trainer.epochs 10`.
 * `config` (`str | None`): Path or URL of the config file. Mutually exclusive with `model`. If omitted, the packaged config of
   `model` applies, else the config stored in the `weights` checkpoint.
 * `model` (`str | None`): Name of a packaged predefined model, for example `"detection"` or `"detection:v1"`. Run `luxonis_train
   list-models` to see the options.
 * `variant` (`str | None`): Variant of the predefined model, for example `"light"` or `"heavy"`. Defaults to the default variant
   of the model.
 * `weights` (`str | None`): Path or URL of a checkpoint. It supplies the config when `config` and `model` are omitted. The trials
   do not load its weights.
 * `debug` (`bool`): When `True`, a
   [DummyLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
   replaces a loader that fails to initialize, so the model builds without a valid dataset.

### upgrade

```python
def upgrade():
```

Upgrade the `luxonis-train` installation.

Without a subcommand, the command reads the latest release from PyPI. When it differs from the installed version, the command
upgrades `pip`, `luxonis_train`, and `luxonis_ml[data]` with pip. When the check fails, the command logs a message and stops. The
`config` and `checkpoint` subcommands upgrade user files instead.

## Attributes

### annotation_group

### app

### evaluation_group

### export_group

### LauncherSource

### management_group

### OptsType

### training_group

### upgrade_app