altametris.sara.yolo.trainer
============================

.. py:module:: altametris.sara.yolo.trainer

.. autoapi-nested-parse::

   YOLO trainer implementation.

   Provides training interface for YOLO models using Ultralytics backend
   with Altametris standardized callbacks and configuration.

   .. rubric:: Example

   >>> model = YoloModel(version="11", task="detect", size="x")
   >>> trainer = YoloTrainer(model=model, device="cuda")
   >>> results = trainer.train(dataset_config="coco128.yaml", epochs=100)



Attributes
----------

.. autoapisummary::

   altametris.sara.yolo.trainer.logger


Classes
-------

.. autoapisummary::

   altametris.sara.yolo.trainer.YoloTrainer


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

.. py:data:: logger

.. py:class:: YoloTrainer(model: altametris.sara.yolo.model.YoloModel, device: str = 'auto', callbacks: Optional[list[altametris.sara.core.base_callback.BaseCallback]] = None)

   Bases: :py:obj:`altametris.sara.core.base_trainer.BaseTrainer`


   YOLO trainer implementing BaseTrainer interface.

   Wraps Ultralytics training with Altametris callback system
   and standardized configuration.

   :param model: YOLO model to train
   :param device: Training device
   :param callbacks: Training callbacks

   .. rubric:: Example

   >>> model = YoloModel(version="11", task="detect", size="n")
   >>> trainer = YoloTrainer(model=model, device="cuda")
   >>> results = trainer.train(
   ...     dataset_config="data.yaml",
   ...     epochs=100,
   ...     batch_size=16,
   ...     imgsz=640
   ... )


   .. py:attribute:: model
      :type:  altametris.sara.yolo.model.YoloModel


   .. py:method:: _resolve_device_for_ultralytics() -> str

      Convert Altametris device format to Ultralytics-compatible format.

      Ultralytics does not support 'auto' device. It requires explicit
      device specification: 'cpu', '0', '1', etc.

      Conversion rules:
          - 'auto' -> 'cpu' (if no GPU) or '0' (if GPU available)
          - 'cuda' -> '0' (first GPU)
          - 'cuda:0' -> '0' (extract GPU index)
          - 'cpu' -> 'cpu' (unchanged)

      :returns: Device string compatible with Ultralytics (e.g., 'cpu', '0')

      .. note::

         This method checks actual GPU availability using torch.cuda.device_count()
         to avoid errors when CUDA is installed but no GPU is present.



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

      Bridge between Altametris callbacks and Ultralytics callbacks.

      Registers hooks into Ultralytics training lifecycle that forward
      events to the Altametris callback manager. This ensures callbacks
      are triggered automatically during Ultralytics training.

      Ultralytics hooks registered:
          - on_train_start: Called when training begins
          - on_train_epoch_end: Called after each training epoch
          - on_val_end: Called after validation
          - on_train_end: Called when training completes

      .. note::

         This method is called automatically during __init__.
         Manual callback invocations in train() are not needed.



   .. py:method:: load_config(config_path: Union[str, pathlib.Path]) -> Dict[str, Any]

      Load and parse YAML configuration file.

      Supports both dataset configuration files (data.yaml) and
      training parameter files (train-params.yaml).

      :param config_path: Path to YAML configuration file

      :returns: Dictionary containing parsed configuration

      :raises TrainingError: If config file not found or invalid YAML

      .. rubric:: Example

      >>> # Load dataset config
      >>> dataset_config = trainer.load_config("data/detect/config.yml")
      >>> print(dataset_config['names'])
      {0: 'Chassis A', 1: 'Chassis C', ...}

      >>> # Load training params
      >>> train_params = trainer.load_config("data/detect/train-parameter-detect.yaml")
      >>> epochs = train_params['train']['epochs']



   .. py:method:: train(dataset_config: Union[str, pathlib.Path, Dict[str, Any]], epochs: int = 100, batch_size: int = 16, imgsz: int = 640, save_dir: Optional[Union[str, pathlib.Path]] = None, **kwargs: Any) -> dict[str, Any]

      Train YOLO model.

      :param dataset_config: Path to dataset YAML configuration or dict
      :param epochs: Number of training epochs
      :param batch_size: Batch size
      :param imgsz: Input image size
      :param save_dir: Directory to save results
      :param \*\*kwargs: Additional Ultralytics training arguments

      :returns: Training results dictionary

      :raises TrainingError: If training fails

      .. rubric:: Example

      >>> # Using YAML path
      >>> results = trainer.train(
      ...     dataset_config="data.yaml",
      ...     epochs=10,
      ...     batch_size=8,
      ...     imgsz=640
      ... )

      >>> # Using dict config
      >>> config = trainer.load_config("train-params.yaml")
      >>> results = trainer.train(
      ...     dataset_config="data.yaml",
      ...     epochs=config['train']['epochs'],
      ...     batch_size=config['train']['batch_size']
      ... )



   .. py:method:: validate(dataset_config: Union[str, pathlib.Path], **kwargs: Any) -> dict[str, Any]

      Validate YOLO model.

      :param dataset_config: Path to validation dataset config
      :param \*\*kwargs: Additional validation arguments

      :returns: Validation metrics

      :raises TrainingError: If validation fails

      .. rubric:: Example

      >>> metrics = trainer.validate(dataset_config="val.yaml")



   .. py:method:: _extract_metrics(results: Any) -> dict[str, Any]

      Extract metrics from Ultralytics results.

      :param results: Ultralytics training/validation results

      :returns: Dictionary of metrics



   .. py:method:: resume_training(checkpoint_path: Union[str, pathlib.Path], **kwargs: Any) -> dict[str, Any]

      Resume training from checkpoint.

      :param checkpoint_path: Path to checkpoint file
      :param \*\*kwargs: Additional training arguments

      :returns: Training results

      .. rubric:: Example

      >>> results = trainer.resume_training("runs/train/exp/weights/last.pt")