"""Auto-generated stub for module: callbacks."""
from typing import Any, List, Set

# Constants
logger: Any

# Functions
def run_callbacks(callbacks: list[Any], hook: str, *args: Any, **kwargs: Any) -> None:
    """
    Fire a named hook on every callback in the list.
    
        Catches and logs exceptions from individual callbacks so that a
        broken callback does not crash the training loop.
    
        Args:
            callbacks: List of :class:`TrainerCallback` instances.
            hook: Method name to invoke (e.g. ``"on_epoch_end"``).
            *args: Positional arguments forwarded to the hook.
            **kwargs: Keyword arguments forwarded to the hook.
    """
    ...

# Classes
class ActionTrackerCallback:
    # Forward per-epoch metrics and key status updates to the ActionTracker.
    #
    #     Registered by default in ``LoopTrainer`` so that every epoch's
    #     train/val metrics are recorded on the platform without any extra
    #     code in the BYOM project.

    def on_epoch_end(self: Any, trainer: Any, epoch: int, metrics: list[dict[str, Any]]) -> None:
        """
        Log epoch metrics via ``action_tracker.log_epoch_results``.
        """
        ...

    def on_train_begin(self: Any, trainer: Any) -> None:
        """
        Send the ``MDL_TRN_STR`` status to signal loop start.
        """
        ...

class CheckpointCallback:
    # Save model checkpoints periodically during training.
    #
    #     By default a checkpoint is written after every epoch that improves
    #     the monitored metric.  Set ``save_every_n_epochs`` to checkpoint at
    #     a fixed cadence regardless of metric changes.
    #
    #     Args:
    #         checkpoint_dir: Directory where checkpoint files are written.
    #         monitor: Metric name that determines "best" (matched against
    #             ``metricName`` in epoch-metrics).
    #         mode: ``"min"`` or ``"max"`` — how *monitor* is compared.
    #         save_every_n_epochs: If set, save a checkpoint every *N* epochs
    #             regardless of metric improvement.  ``None`` means save only
    #             when the monitored metric improves.

    def __init__(self: Any, checkpoint_dir: str | Any = 'checkpoints', monitor: str = 'loss', mode: str = 'min', save_every_n_epochs: int | None = None) -> None:
        """
        Initialize checkpoint state.
        
                Args:
                    checkpoint_dir: Target directory for checkpoint files.
                    monitor: ``metricName`` string to track for best-model logic.
                    mode: ``"min"`` (loss-like) or ``"max"`` (accuracy-like).
                    save_every_n_epochs: Fixed checkpoint cadence, or ``None``
                        for best-only saving.
        """
        ...

    def on_epoch_end(self: Any, trainer: Any, epoch: int, metrics: list[dict[str, Any]]) -> None:
        """
        Save a checkpoint if conditions are met.
        """
        ...

class EarlyStoppingCallback:
    # Stop training when a monitored metric stops improving.
    #
    #     Tracks the value of *monitor* across epochs.  If the metric does
    #     not improve by at least *min_delta* for *patience* consecutive
    #     epochs, :attr:`should_stop` is set to ``True`` and the training
    #     loop should break.
    #
    #     Args:
    #         patience: Number of epochs to wait without improvement.
    #         min_delta: Minimum change to qualify as an improvement.
    #         monitor: Metric name to watch (matched against the
    #             ``metricName`` key in the epoch-metrics list).
    #         mode: ``"min"`` treats lower values as better (e.g. loss),
    #             ``"max"`` treats higher values as better (e.g. accuracy).

    def __init__(self: Any, patience: int = 5, min_delta: float = 0.0, monitor: str = 'loss', mode: str = 'min') -> None:
        """
        Initialize early-stopping state.
        
                Args:
                    patience: Epochs without improvement before stopping.
                    min_delta: Minimum absolute improvement threshold.
                    monitor: ``metricName`` string to track in epoch metrics.
                    mode: ``"min"`` (loss-like) or ``"max"`` (accuracy-like).
        """
        ...

    def on_epoch_end(self: Any, trainer: Any, epoch: int, metrics: list[dict[str, Any]]) -> None:
        """
        Check the monitored metric and update the patience counter.
        """
        ...

class TrainerCallback:
    # Base callback with no-op defaults for every hook.
    #
    #     Subclass and override only the methods you need.  Any method not
    #     overridden silently does nothing, so new hooks can be added in
    #     future releases without breaking existing callbacks.
    #
    #     Hook firing order inside ``LoopTrainer.train_loop``::
    #
    #         on_train_begin(trainer)
    #         for epoch in range(epochs):
    #             on_epoch_begin(trainer, epoch)
    #             ... train + validate ...
    #             on_epoch_end(trainer, epoch, metrics)
    #         on_train_end(trainer, result)

    def on_epoch_begin(self: Any, trainer: Any, epoch: int) -> None:
        """
        Called at the start of each epoch.
        
                Args:
                    trainer: The active ``Trainer`` instance.
                    epoch: Zero-based epoch index.
        """
        ...

    def on_epoch_end(self: Any, trainer: Any, epoch: int, metrics: list[dict[str, Any]]) -> None:
        """
        Called after training *and* validation for one epoch complete.
        
                Args:
                    trainer: The active ``Trainer`` instance.
                    epoch: Zero-based epoch index.
                    metrics: Epoch metrics in ActionTracker format — a list of
                        dicts each containing ``splitType``, ``metricName``, and
                        ``metricValue``.
        """
        ...

    def on_train_begin(self: Any, trainer: Any) -> None:
        """
        Called once before the first epoch.
        
                Args:
                    trainer: The active ``Trainer`` instance.
        """
        ...

    def on_train_end(self: Any, trainer: Any, result: Any) -> None:
        """
        Called once after the last epoch (or early-stop).
        
                Args:
                    trainer: The active ``Trainer`` instance.
                    result: The :class:`TrainResult` produced by the training loop.
        """
        ...

