altametris.sara.yolo.callbacks
==============================

.. py:module:: altametris.sara.yolo.callbacks

.. autoapi-nested-parse::

   YOLO-specific callbacks.

   Specialized callbacks for YOLO training with metrics logging,
   checkpoint management, and early stopping.

   .. rubric:: Example

   >>> callback = YoloMetricsCallback()
   >>> trainer = YoloTrainer(model=model, callbacks=[callback])



Attributes
----------

.. autoapisummary::

   altametris.sara.yolo.callbacks.logger


Classes
-------

.. autoapisummary::

   altametris.sara.yolo.callbacks.YoloMetricsCallback
   altametris.sara.yolo.callbacks.YoloCheckpointCallback
   altametris.sara.yolo.callbacks.YoloEarlyStoppingCallback
   altametris.sara.yolo.callbacks.YoloLoggingCallback


Module Contents
---------------

.. py:data:: logger

.. py:class:: YoloMetricsCallback(log_file: Optional[pathlib.Path] = None)

   Bases: :py:obj:`altametris.sara.core.base_callback.BaseCallback`


   Callback for logging YOLO training metrics.

   Logs mAP, precision, recall, and loss metrics during training.

   .. rubric:: Example

   >>> callback = YoloMetricsCallback(log_file="metrics.json")
   >>> trainer = YoloTrainer(model=model, callbacks=[callback])


   .. py:attribute:: log_file
      :value: None



   .. py:attribute:: metrics_history
      :type:  list[dict[str, Any]]
      :value: []



   .. py:method:: on_epoch_end(epoch: int, metrics: dict[str, Any], **kwargs: Any) -> None

      Log metrics at end of epoch.



   .. py:method:: _save_metrics() -> None

      Save metrics history to JSON file.



.. py:class:: YoloCheckpointCallback(save_dir: pathlib.Path, monitor_metric: str = 'mAP50', save_every: int = 10)

   Bases: :py:obj:`altametris.sara.core.base_callback.BaseCallback`


   Callback for saving model checkpoints.

   Saves best model based on specified metric and periodic checkpoints.

   :param save_dir: Directory to save checkpoints
   :param monitor_metric: Metric to monitor for best model (default: "mAP50")
   :param save_every: Save checkpoint every N epochs

   .. rubric:: Example

   >>> callback = YoloCheckpointCallback(
   ...     save_dir="checkpoints",
   ...     monitor_metric="mAP50-95",
   ...     save_every=10
   ... )


   .. py:attribute:: save_dir


   .. py:attribute:: monitor_metric
      :value: 'mAP50'



   .. py:attribute:: save_every
      :value: 10



   .. py:attribute:: best_metric
      :value: 0.0



   .. py:method:: on_epoch_end(epoch: int, metrics: dict[str, Any], **kwargs: Any) -> None

      Save checkpoints at end of epoch.



   .. py:method:: _save_checkpoint(model: altametris.sara.core.base_model.BaseModel, path: pathlib.Path, checkpoint_type: str) -> None

      Helper to save checkpoint with error handling.



.. py:class:: YoloEarlyStoppingCallback(monitor_metric: str = 'mAP50', patience: int = 20, min_delta: float = 0.001)

   Bases: :py:obj:`altametris.sara.core.base_callback.BaseCallback`


   Callback for early stopping based on metric plateau.

   Stops training if monitored metric doesn't improve for N epochs.

   :param monitor_metric: Metric to monitor
   :param patience: Number of epochs without improvement before stopping
   :param min_delta: Minimum change to qualify as improvement

   .. rubric:: Example

   >>> callback = YoloEarlyStoppingCallback(
   ...     monitor_metric="val_loss",
   ...     patience=20,
   ...     min_delta=0.001
   ... )


   .. py:attribute:: monitor_metric
      :value: 'mAP50'



   .. py:attribute:: patience
      :value: 20



   .. py:attribute:: min_delta
      :value: 0.001



   .. py:attribute:: best_metric
      :value: 0.0



   .. py:attribute:: epochs_without_improvement
      :value: 0



   .. py:attribute:: should_stop
      :value: False



   .. py:method:: on_epoch_end(epoch: int, metrics: dict[str, Any], **kwargs: Any) -> None

      Check for early stopping condition.



.. py:class:: YoloLoggingCallback(log_level: str = 'INFO')

   Bases: :py:obj:`altametris.sara.core.base_callback.BaseCallback`


   Callback for structured logging of training progress.

   Logs training events with timestamps and structured data.

   .. rubric:: Example

   >>> callback = YoloLoggingCallback(log_level="INFO")
   >>> trainer = YoloTrainer(model=model, callbacks=[callback])


   .. py:attribute:: log_level


   .. py:method:: on_train_start(**kwargs: Any) -> None

      Log training start.



   .. py:method:: on_train_end(**kwargs: Any) -> None

      Log training end.



   .. py:method:: on_validation_start(**kwargs: Any) -> None

      Log validation start.



   .. py:method:: on_validation_end(metrics: dict[str, Any], **kwargs: Any) -> None

      Log validation results.