"""Auto-generated stub for module: loop_trainer."""
from typing import Any, Optional

# Constants
logger: Any

# Classes
class LoopTrainer:
    # Trainer with a standard PyTorch epoch loop.
    #
    #     Subclasses implement four extra hooks beyond the ones inherited from
    #     :class:`Trainer`:
    #
    #     ==================  ======================================================
    #     Hook                Responsibility
    #     ==================  ======================================================
    #     configure_criterion Return the loss function (e.g. ``nn.CrossEntropyLoss``)
    #     configure_optimizer Return the optimiser for ``self.model``
    #     train_one_epoch     Run one training epoch, return a flat metrics dict
    #     validate_one_epoch  Run one validation epoch, return a flat metrics dict
    #     ==================  ======================================================
    #
    #     Optionally override :meth:`configure_scheduler` to add a learning-rate
    #     schedule.
    #
    #     The built-in :meth:`train_loop` then orchestrates:
    #
    #     1. Criterion / optimiser / scheduler creation.
    #     2. ``on_train_begin`` callback.
    #     3. Per-epoch: ``on_epoch_begin`` → train → validate → scheduler step
    #        → format metrics → ``on_epoch_end`` → checkpoint → early-stop check.
    #     4. ``on_train_end`` callback and :class:`TrainResult` population.

    def __init__(self: Any, action_id: str | None, model_info: Any, config: Any) -> None:
        """
        Initialise the loop trainer.
        
                Args:
                    action_id: Platform action ID (``None`` for local runs).
                    model_info: Model identity and capabilities.
                    config: Training hyperparameters.
                    checkpoint_dir: Directory for checkpoint files.
                    callbacks: Optional list of callbacks.  Defaults to
                        ``[ActionTrackerCallback()]``.
                    monitor: Validation metric to track for *best model*
                        selection.  Must match a key returned by
                        :meth:`validate_one_epoch`.
                    monitor_mode: ``"max"`` when higher is better (accuracy)
                        or ``"min"`` when lower is better (loss).
        """
        ...

    def configure_criterion(self: Any) -> Any.Any:
        """
        Return the loss function.
        
                Called once before the epoch loop begins.  The returned module
                is stored as ``self.criterion`` so :meth:`train_one_epoch` and
                :meth:`validate_one_epoch` can access it.
        
                Example::
        
                    def configure_criterion(self) -> nn.Module:
                        return nn.CrossEntropyLoss().to(self.device)
        """
        ...

    def configure_optimizer(self: Any) -> Any.Any:
        """
        Return the optimiser for ``self.model``.
        
                Called once after ``setup_model`` has populated ``self.model``
                and the device has been resolved.  The returned optimiser is
                stored as ``self.optimizer``.
        
                Example::
        
                    def configure_optimizer(self) -> optim.Optimizer:
                        return torch.optim.AdamW(
                            self.model.parameters(),
                            lr=self.config.learning_rate,
                        )
        """
        ...

    def configure_scheduler(self: Any) -> Any | None:
        """
        Return an optional learning-rate scheduler.
        
                Called once after :meth:`configure_optimizer`.  The default
                returns ``None`` (constant LR).  Override to add e.g.
                ``StepLR``, ``CosineAnnealingLR``, etc.
        
                Returns:
                    A scheduler instance, or ``None`` for constant LR.
        
                Example::
        
                    def configure_scheduler(self) -> LRScheduler:
                        return torch.optim.lr_scheduler.StepLR(
                            self.optimizer,
                            step_size=30,
                            gamma=0.1,
                        )
        """
        ...

    def train_loop(self: Any) -> None:
        """
        Execute the standard PyTorch training loop.
        
                Lifecycle::
        
                    configure_criterion → configure_optimizer → configure_scheduler
                    on_train_begin
                    for epoch in range(epochs):
                        on_epoch_begin
                        train_one_epoch  →  validate_one_epoch  →  scheduler.step()
                        format_metrics → on_epoch_end → log_epoch → checkpoint → early_stop?
                    on_train_end(result)
        
                Populates ``self._result`` before returning.
        """
        ...

    def train_one_epoch(self: Any, epoch: int) -> dict[str, float]:
        """
        Run one training epoch and return metrics.
        
                Typical implementations iterate ``self.train_loader``, compute
                the forward/backward pass, and accumulate metrics.
        
                The trainer guarantees that ``self.model``, ``self.criterion``,
                ``self.optimizer``, and ``self.device`` are already set.
        
                Args:
                    epoch: Zero-based epoch index.
        
                Returns:
                    Flat dict of metric values, e.g.
                    ``{"loss": 0.45, "acc@1": 0.82, "acc@5": 0.96}``.
        """
        ...

    def validate_one_epoch(self: Any, epoch: int) -> dict[str, float]:
        """
        Run one validation epoch and return metrics.
        
                Similar to :meth:`train_one_epoch` but in ``torch.no_grad()``
                mode and without gradient updates.
        
                Args:
                    epoch: Zero-based epoch index.
        
                Returns:
                    Flat dict of metric values, e.g.
                    ``{"loss": 0.52, "acc@1": 0.78, "acc@5": 0.94}``.
                    Return an **empty dict** if no validation set exists.
        """
        ...

