Callbacks

Callbacks allow users to inject custom logic into the training process, such as early stopping, checkpointing, and logging.

Callbacks are executed at predefined hook points during training.

---

keydnn.Callback

Base class for Keras-style training callbacks.

Subclasses may override any subset of the hook methods below. All hook methods are optional and default to no-ops.

Supported hooks

• set_model(model): called once before training begins.
• on_train_begin(logs), on_train_end(logs)
• on_epoch_begin(epoch, logs), on_epoch_end(epoch, logs)
• on_batch_begin(batch, logs), on_batch_end(batch, logs)

Attributes:

Name	Type	Description
model	Any	The model instance being trained. Set by set_model(model).

Notes

• logs is typically a dict of Python floats, but callers may pass any mapping-like structure as long as metric values are scalar-like.
• To request early termination, a callback may set self.stop_training = True.

set_model

set_model(model: Any) -> None

Attach the model being trained to this callback.

This method is called once before training begins and allows callbacks to store a reference to the model for later use.

Parameters:

Name	Type	Description	Default
model	Any	The model instance that will be trained.	required

on_train_begin

on_train_begin(
    logs: Optional[Dict[str, float]] = None,
) -> None

Hook called at the very beginning of training.

Parameters:

Name	Type	Description	Default
logs	dict[str, float]	Initial training logs, typically empty or containing global metrics.	None

on_train_end

on_train_end(
    logs: Optional[Dict[str, float]] = None,
) -> None

Hook called at the very end of training.

Parameters:

Name	Type	Description	Default
logs	dict[str, float]	Final training logs.	None

on_epoch_begin

on_epoch_begin(
    epoch: int, logs: Optional[Dict[str, float]] = None
) -> None

Hook called at the beginning of an epoch.

Parameters:

Name	Type	Description	Default
epoch	int	Zero-based epoch index.	required
logs	dict[str, float]	Logs available at the start of the epoch.	None

on_epoch_end

on_epoch_end(
    epoch: int, logs: Optional[Dict[str, float]] = None
) -> None

Hook called at the end of an epoch.

Parameters:

Name	Type	Description	Default
epoch	int	Zero-based epoch index.	required
logs	dict[str, float]	Logs aggregated over the epoch.	None

on_batch_begin

on_batch_begin(
    batch: int, logs: Optional[Dict[str, float]] = None
) -> None

Hook called at the beginning of a batch.

Parameters:

Name	Type	Description	Default
batch	int	Zero-based batch index within the current epoch.	required
logs	dict[str, float]	Logs available at the start of the batch.	None

on_batch_end

on_batch_end(
    batch: int, logs: Optional[Dict[str, float]] = None
) -> None

Hook called at the end of a batch.

Parameters:

Name	Type	Description	Default
batch	int	Zero-based batch index within the current epoch.	required
logs	dict[str, float]	Logs aggregated over the batch.	None

---

keydnn.CallbackList

Dispatch training events to a sequence of callbacks.

CallbackList is used by training loops (e.g., Model.fit()) to forward events to multiple callbacks while tracking a shared stop_training flag.

Attributes:

Name	Type	Description
callbacks	List[Callback]	Registered callbacks to receive events.
stop_training	bool	Set to True if any callback requests termination (by setting an attribute stop_training to True). The training loop should stop after the current epoch completes.

set_model

set_model(model: Any) -> None

Attach the model to all registered callbacks.

Parameters:

Name	Type	Description	Default
model	Any	The model instance being trained.	required

on_train_begin

on_train_begin(
    logs: Optional[Dict[str, float]] = None,
) -> None

Forward the training-begin event to all callbacks.

Parameters:

Name	Type	Description	Default
logs	dict[str, float]	Initial training logs.	None

on_train_end

on_train_end(
    logs: Optional[Dict[str, float]] = None,
) -> None

Forward the training-end event to all callbacks.

Parameters:

Name	Type	Description	Default
logs	dict[str, float]	Final training logs.	None

on_epoch_begin

on_epoch_begin(
    epoch: int, logs: Optional[Dict[str, float]] = None
) -> None

Forward the epoch-begin event to all callbacks.

Parameters:

Name	Type	Description	Default
epoch	int	Zero-based epoch index.	required
logs	dict[str, float]	Logs available at the start of the epoch.	None

on_epoch_end

on_epoch_end(
    epoch: int, logs: Optional[Dict[str, float]] = None
) -> None

Forward the epoch-end event to all callbacks and update stop flags.

Parameters:

Name	Type	Description	Default
epoch	int	Zero-based epoch index.	required
logs	dict[str, float]	Logs aggregated over the epoch.	None

on_batch_begin

on_batch_begin(
    batch: int, logs: Optional[Dict[str, float]] = None
) -> None

Forward the batch-begin event to all callbacks.

Parameters:

Name	Type	Description	Default
batch	int	Zero-based batch index.	required
logs	dict[str, float]	Logs available at the start of the batch.	None

on_batch_end

on_batch_end(
    batch: int, logs: Optional[Dict[str, float]] = None
) -> None

Forward the batch-end event to all callbacks and update stop flags.

Parameters:

Name	Type	Description	Default
batch	int	Zero-based batch index.	required
logs	dict[str, float]	Logs aggregated over the batch.	None

---

keydnn.EarlyStopping

Bases: Callback

Stop training when a monitored metric has stopped improving.

This callback monitors a metric in logs (e.g., "val_loss") at epoch end. If the metric fails to improve for more than patience epochs, it sets self.stop_training = True, which the training loop should respect (typically stopping after the current epoch). # NOTE: original text unchanged

Restore best weights (in-memory)

If restore_best_weights=True, EarlyStopping snapshots the model at the best epoch and restores it when stopping criteria are met.

The snapshot/restore is performed entirely in memory using the optional model methods: - model.to_json_payload() -> dict - model.from_json_payload_(payload: dict) -> None

If these methods are not available, restore_best_weights=True degrades gracefully to "stop-only" behavior.

Parameters:

Name	Type	Description	Default
monitor	str	Metric name to monitor, e.g. "val_loss" or "loss". Default "val_loss".	'val_loss'
mode	str	One of {"min", "max", "auto"}: - "min": lower is better (e.g., loss) - "max": higher is better (e.g., accuracy) - "auto": infer direction from monitor name ("acc"/"accuracy" -> max; else min)	'auto'
patience	int	Number of epochs with no improvement to tolerate before stopping. Default 0.	0
min_delta	float	Minimum absolute change required to count as improvement. Default 0.0.	0.0
restore_best_weights	bool	If True, attempt to restore model weights from the best epoch using the in-memory payload interface. Default False.	False

Attributes:

Name	Type	Description
best	float	Best metric value observed so far.
best_epoch	Optional[int]	Zero-based epoch index where the best value was observed.
stopped_epoch	Optional[int]	Zero-based epoch index where stopping was triggered.
stop_training	bool	Set to True when stopping criteria are met.

Notes

• Patience is evaluated using wait > patience (Keras-like in spirit, but exact off-by-one behavior depends on the training loop cadence).
• Improvement logic is shared across callbacks via _is_better.

set_model

set_model(model: Any) -> None

Attach the model being trained to this callback.

This method is called once before training begins and allows callbacks to store a reference to the model for later use.

Parameters:

Name	Type	Description	Default
model	Any	The model instance that will be trained.	required

on_train_end

on_train_end(
    logs: Optional[Dict[str, float]] = None,
) -> None

Hook called at the very end of training.

Parameters:

Name	Type	Description	Default
logs	dict[str, float]	Final training logs.	None

on_epoch_begin

on_epoch_begin(
    epoch: int, logs: Optional[Dict[str, float]] = None
) -> None

Hook called at the beginning of an epoch.

Parameters:

Name	Type	Description	Default
epoch	int	Zero-based epoch index.	required
logs	dict[str, float]	Logs available at the start of the epoch.	None

on_batch_begin

on_batch_begin(
    batch: int, logs: Optional[Dict[str, float]] = None
) -> None

Hook called at the beginning of a batch.

Parameters:

Name	Type	Description	Default
batch	int	Zero-based batch index within the current epoch.	required
logs	dict[str, float]	Logs available at the start of the batch.	None

on_batch_end

on_batch_end(
    batch: int, logs: Optional[Dict[str, float]] = None
) -> None

Hook called at the end of a batch.

Parameters:

Name	Type	Description	Default
batch	int	Zero-based batch index within the current epoch.	required
logs	dict[str, float]	Logs aggregated over the batch.	None

on_train_begin

on_train_begin(
    logs: Optional[Dict[str, float]] = None,
) -> None

Initialize internal state at the start of training.

This resets the best metric value, wait counter, bookkeeping attributes, and any stored in-memory snapshot.

Parameters:

Name	Type	Description	Default
logs	dict[str, float]	Initial training logs (unused).	None

on_epoch_end

on_epoch_end(
    epoch: int, logs: Optional[Dict[str, float]] = None
) -> None

Check monitored metric at epoch end and update stopping state.

If the monitored metric improves, internal best-tracking state is updated and (optionally) an in-memory model snapshot is taken. Otherwise, the patience counter is incremented and training may be stopped once patience is exceeded.

Parameters:

Name	Type	Description	Default
epoch	int	Zero-based epoch index.	required
logs	dict[str, float]	Metrics logged for the completed epoch.	None

---

keydnn.ModelCheckpoint

Bases: Callback

Save model checkpoints during training.

ModelCheckpoint writes checkpoints via the model's save_json(path) method. It supports saving at the end of every epoch or only when a monitored metric improves (best-only), similar to Keras.

Formatting

filepath may be a plain path or a format string. If it contains Python format fields, they are formatted with: - epoch: the 1-based epoch number (Keras-like) - all keys present in logs (e.g., loss, val_loss, etc.)

Parameters:

Name	Type	Description	Default
filepath	str | Path	Output path or a path template.	required
monitor	str	Name of the metric to monitor for best-only saving. Default is "val_loss".	'val_loss'
mode	str	One of {"min", "max", "auto"} determining optimization direction.	'auto'
save_best_only	bool	If True, only save checkpoints when monitor improves.	True
verbose	int	If non-zero, prints save decisions.	0

set_model

set_model(model: Any) -> None

Attach the model being trained to this callback.

This method is called once before training begins and allows callbacks to store a reference to the model for later use.

Parameters:

Name	Type	Description	Default
model	Any	The model instance that will be trained.	required

on_train_end

on_train_end(
    logs: Optional[Dict[str, float]] = None,
) -> None

Hook called at the very end of training.

Parameters:

Name	Type	Description	Default
logs	dict[str, float]	Final training logs.	None

on_epoch_begin

on_epoch_begin(
    epoch: int, logs: Optional[Dict[str, float]] = None
) -> None

Hook called at the beginning of an epoch.

Parameters:

Name	Type	Description	Default
epoch	int	Zero-based epoch index.	required
logs	dict[str, float]	Logs available at the start of the epoch.	None

on_batch_begin

on_batch_begin(
    batch: int, logs: Optional[Dict[str, float]] = None
) -> None

Hook called at the beginning of a batch.

Parameters:

Name	Type	Description	Default
batch	int	Zero-based batch index within the current epoch.	required
logs	dict[str, float]	Logs available at the start of the batch.	None

on_batch_end

on_batch_end(
    batch: int, logs: Optional[Dict[str, float]] = None
) -> None

Hook called at the end of a batch.

Parameters:

Name	Type	Description	Default
batch	int	Zero-based batch index within the current epoch.	required
logs	dict[str, float]	Logs aggregated over the batch.	None

on_train_begin

on_train_begin(
    logs: Optional[Dict[str, float]] = None,
) -> None

Initialize internal state at the start of training.

This sets the initial best metric value according to the resolved optimization direction.

Parameters:

Name	Type	Description	Default
logs	dict[str, float]	Initial training logs (unused).	None

on_epoch_end

on_epoch_end(
    epoch: int, logs: Optional[Dict[str, float]] = None
) -> None

Save a model checkpoint at epoch end if criteria are met.

Depending on configuration, this method either saves a checkpoint unconditionally or only when the monitored metric improves.

Parameters:

Name	Type	Description	Default
epoch	int	Zero-based epoch index.	required
logs	dict[str, float]	Metrics logged for the completed epoch.	None

---

Notes

• Custom callbacks should subclass Callback and override the relevant hook methods.
• Callbacks are typically passed as a list or managed via CallbackList.
• The exact hook order and lifecycle are documented in the base Callback class.