# predefined

Python API: `luxonis_train.config.predefined`

Look up the config files of the predefined models in the package.

The `--model` and `--variant` options of the `luxonis_train` commands, and the `model` and `variant` arguments of
[LuxonisModel](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md),
go through
[resolve_predefined_config](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md).
A packaged file `<model>_<variant>_model.yaml` or `<model>_model.yaml` in
[luxonis_train.configs](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/configs.md)
defines a model name and its variants.

## Classes

### ResolvedPredefinedConfig

A packaged config file and the overrides that go with it.

#### Attributes

##### opts

Config overrides as alternating keys and values, such as `model.predefined_model.variant` followed by `medium`. The list is empty
when the file needs no override.

##### path

The path of the packaged YAML file.

## Functions

### class_family

```python
def class_family(model: str) -> str | None:
```

Return the class name in the default config file of a model.

The function reads `model.predefined_model.name` from the file of
[default_config_path](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md).

> **Example**
> ```pycon
>>> class_family("keypoint_bbox")
'KeypointDetectionModel'
>>> print(class_family("unknown"))
None
```

Parameters

 * `model` (`str`): The model name, without a version suffix.

Returns

 * `str | None`: The value of `model.predefined_model.name`. `None` when `model` is not a packaged model. Also `None` when the function cannot read the file, when the file is not valid YAML, or when the file has no such key.

### configs_dir

```python
def configs_dir() -> Path:
```

Return the directory of the packaged config files.

> **Example**
> ```pycon
>>> configs_dir().name
'configs'
```

Returns

 * `Path`: The directory of the
   [luxonis_train.configs](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/configs.md)
   package.

### default_config_path

```python
def default_config_path(model: str) -> Path:
```

Return the config file of the default variant of a model.

The default variant is the first variant that
[list_predefined_models](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md)
gives for `model`.

> **Example**
> ```pycon
>>> default_config_path("detection").name
'detection_light_model.yaml'
```

Parameters

 * `model` (`str`): The model name, without a version suffix.

Returns

 * `Path`: The path of the packaged YAML file.

Raises

 * `KeyError`: When `model` is not a packaged model.

### list_predefined_models

```python
def list_predefined_models() -> dict[str, list[str | None]]:
```

List the packaged models and the variants that have a file.

The function reads the names of the files in [configs_dir](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md) that end with `_model.yaml`. It skips `complex_model.yaml` and the other example files. A name that ends with `_<variant>_model.yaml`, for a variant in [VARIANT_ORDER](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md), gives the model and that variant. Any other name `<model>_model.yaml` gives the model and the variant `None`. The list does not hold the variants that only the model class declares. [list_variants](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md) adds them.

> **Example**
> ```pycon
>>> models = list_predefined_models()
>>> models["detection"], models["embeddings"]
(['light', 'heavy'], [None])
```

Returns

 * `dict[str, list[str | None]]`: Each model name mapped to its variants, in the order of
   [VARIANT_ORDER](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md).
   The first variant is the default. The models are in alphabetical order.

### list_variants

```python
def list_variants(model: str) -> list[str | None]:
```

List every variant that a packaged model accepts.

The list holds the variants of
[list_predefined_models](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md),
and the variants that `get_variants` of the model class declares. The model class comes from
[class_family](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md),
in its latest registered version. The function imports the predefined models to find it. When the function cannot resolve the
class, or the class has no variants, the list holds only the variants with a file.

> **Example**
> ```pycon
>>> list_variants("detection")
['light', 'medium', 'heavy']
>>> list_variants("anomaly_detection")
['light', 'heavy', None]
```

Parameters

 * `model` (`str`): The model name, without a version suffix.

Returns

 * `list[str | None]`: The variants in the order of [VARIANT_ORDER](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md). `None` stands for a file without a variant name. The list is empty when `model` is not a packaged model.

### parse_model_spec

```python
def parse_model_spec(model: str) -> tuple[str, str | None]:
```

Split a model name from its optional version suffix.

The suffix follows a `:`. It is `v` with ASCII digits, or `latest`.

> **Example**
> ```pycon
>>> parse_model_spec("detection:v2")
('detection', '2')
>>> parse_model_spec("detection")
('detection', None)
```

Parameters

 * `model` (`str`): The model name, as `"<name>"`, `"<name>:v<N>"`, or `"<name>:latest"`.

Returns

 * `tuple[str, str | None]`: The name, and the version. The version is the digits without `v`, `"latest"`, or `None` when `model`
   has no `:`.

Raises

 * `ValueError`: When the text after `:` is neither `v` with digits nor `latest`.

### resolve_predefined_config

```python
def resolve_predefined_config(model: str, variant: str | None) -> ResolvedPredefinedConfig:
```

Find the config file and the overrides for a model and a variant.

The function selects the file and the overrides as follows:

 * A version other than `latest` becomes the override `model.predefined_model.version`.
 * Without `variant`, the file is the default config file of the model, as in
   [default_config_path](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md).
 * A variant with its own file selects that file.
 * A variant that only the model class declares selects the default config file.

In the last two cases, `variant` also becomes the override `model.predefined_model.variant`, so it replaces the variant that the
file sets.

> **Example**
> ```pycon
>>> path, opts = resolve_predefined_config("detection:v1", "medium")
>>> path.name
'detection_light_model.yaml'
>>> opts
['model.predefined_model.version', '1',
 'model.predefined_model.variant', 'medium']
```

Parameters

 * `model` (`str`): The model name, with an optional version suffix, as in [parse_model_spec](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md).
 * `variant` (`str | None`): The variant. `None` selects the default config file and adds no variant override.

Returns

 * `ResolvedPredefinedConfig`: The path of the file and the overrides.

Raises

 * `ValueError`: When the version suffix is malformed, when `model` is not a packaged model, or when `variant` is not in [list_variants](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md).

## Attributes

### CONFIGS_PACKAGE

### VARIANT_ORDER