# needs_checkpoint

Python API: `luxonis_train.callbacks.needs_checkpoint`

The base class of the callbacks that act on the best checkpoint.

[NeedsCheckpoint.get_checkpoint](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/needs_checkpoint.md)
returns the path of the checkpoint with the best main metric or with the lowest validation loss. When the preferred checkpoint
does not exist, it tries the other one. When neither exists, it returns `None`, and each subclass decides what to do.

## Classes

### NeedsCheckpoint

Base class of the callbacks that act on the best checkpoint.

[ArchiveOnTrainEnd](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/archive_on_train_end.md),
[ConvertOnTrainEnd](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/convert_on_train_end.md),
[ExportOnTrainEnd](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/export_on_train_end.md),
[AIMETCallback](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/aimet_callback.md),
and
[TestOnTrainEnd](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/test_on_train_end.md)
inherit from it. Each one calls
[get_checkpoint](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/needs_checkpoint.md)
in its `on_train_end` hook.
[ArchiveOnTrainEnd](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/archive_on_train_end.md)
calls it only when no earlier ONNX export exists. This class defines no hook of its own.

#### Methods

##### init

```python
def __init__(preferred_checkpoint: Literal['metric', 'loss'] = 'metric', **kwargs):
```

Initialize the callback.

Parameters

 * `preferred_checkpoint` (`Literal['metric', 'loss']`): The checkpoint to try first. `"metric"` selects the best main metric, and
   `"loss"` selects the lowest validation loss. The constructor does not check the value. Any value other than `"loss"` acts as
   `"metric"`.
 * `**kwargs`: Keyword arguments for `pl.Callback`. That class accepts none, so any key raises `TypeError`.

##### get_checkpoint

```python
def get_checkpoint(pl_module: lxt.LuxonisLightningModule) -> str | None:
```

Return the path of the best checkpoint.

The method reads the `best_model_path` of a `ModelCheckpoint` callback through `pl_module.core`. It calls
[LuxonisModel.get_best_metric_checkpoint_path](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
for `"metric"` and
[LuxonisModel.get_min_loss_checkpoint_path](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
for `"loss"`. The metric checkpoint exists only when the config has a metric. Without an `is_main_metric` flag, the config makes
the first metric the main metric. A path stays empty until its callback saves a checkpoint.

The method tries `preferred_checkpoint` first. When that path is `None` or empty, it logs an error and an info message, and tries
the other checkpoint. It logs a second error when that path is missing too.

Both getters run on rank zero only and return `None` on every other rank. There, the method logs the same three messages and
returns `None`.

Parameters

 * `pl_module` (`lxt.LuxonisLightningModule`): The module of the run. Its
   [LuxonisModel](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
   holds the trainer and its callbacks.

Returns

 * `str | None`: The path of the checkpoint file, or `None` when neither checkpoint exists.