trainloop 0.9.0__tar.gz → 0.11.0__tar.gz

{trainloop-0.9.0 → trainloop-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: trainloop
-Version: 0.9.0
+Version: 0.11.0
 Summary: Minimal PyTorch training loop with hooks and checkpointing.
 Author: Karim Knaebel
 Author-email: Karim Knaebel <contact@knaebel.dev>

{trainloop-0.9.0 → trainloop-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "trainloop"
-version = "0.9.0"
+version = "0.11.0"
 description = "Minimal PyTorch training loop with hooks and checkpointing."
 readme = "README.md"
 requires-python = ">=3.10"

{trainloop-0.9.0 → trainloop-0.11.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "trainloop"
-version = "0.9.0"
+version = "0.11.0"
 description = "Minimal PyTorch training loop with hooks and checkpointing."
 readme = "README.md"
 authors = [

{trainloop-0.9.0 → trainloop-0.11.0}/src/trainloop/hooks.py

@@ -83,7 +83,9 @@ class BaseHook:
     def on_after_train(self, trainer: BaseTrainer):
         pass
 
-    def on_log(self, trainer: BaseTrainer, records: dict, dry_run: bool = False):
+    def on_log_scalars(
+        self, trainer: BaseTrainer, records: dict, dry_run: bool = False
+    ):
         pass
 
     def on_log_images(self, trainer: BaseTrainer, records: dict, dry_run: bool = False):
@@ -588,14 +590,18 @@ class EMAHook(BaseHook):
     Args:
         decay: EMA decay rate.
         use_buffers: Whether to include model buffers in the EMA.
+        name: Name used for the EMA state in the trainer state dict.
     """
 
-    def __init__(self, decay: float = 0.999, use_buffers: bool = False):
+    def __init__(
+        self, decay: float = 0.999, use_buffers: bool = False, name: str = "ema"
+    ):
         self.decay = decay
         self.use_buffers = use_buffers
+        self.name = name
 
     def on_before_train(self, trainer: BaseTrainer):
-        trainer.logger.info("=> Creating EMA model ...")
+        trainer.logger.info(f"=> Creating EMA model {self.name!r} ...")
         # Note that AveragedModel does not seem to support FSDP. It will crash here.
         self.ema_model = AveragedModel(
             trainer.model,
@@ -608,10 +614,8 @@ class EMAHook(BaseHook):
         self.ema_model.update_parameters(trainer.model)
 
     def on_load_state_dict(self, trainer: BaseTrainer, state_dict: dict):
-        trainer.logger.info("=> Loading EMA model state ...")
-        incompatible_keys = set_model_state_dict(
-            self.ema_model, state_dict["ema_model"]
-        )
+        trainer.logger.info(f"=> Loading EMA model {self.name!r} state ...")
+        incompatible_keys = set_model_state_dict(self.ema_model, state_dict[self.name])
         # This currently doesn't do anything because strict=True is implicit.
         log_state_dict_incompatible_keys(
             trainer.logger,
@@ -620,13 +624,18 @@ class EMAHook(BaseHook):
         )
 
     def on_state_dict(self, trainer: BaseTrainer, state_dict: dict):
+        if self.name in state_dict:
+            raise ValueError(f"State dict key {self.name!r} already exists")
         # Note: sadly, we need to keep the AveragedModel wrapper, to save its n_averaged buffer
-        state_dict["ema_model"] = get_model_state_dict(self.ema_model)
+        state_dict[self.name] = get_model_state_dict(self.ema_model)
 
 
 class WandbHook(BaseHook):
     """Log metrics and images to Weights & Biases (rank 0 only).
 
+    Nested scalar key components are joined with ``/``. Avoid ``/`` within an
+    individual component because it is also W&B's panel namespace separator.
+
     Args:
         project: W&B project name.
         config: Optional config dict or JSON file path to log.
@@ -678,7 +687,9 @@ class WandbHook(BaseHook):
         if _dist_rank() == 0:
             self.wandb.finish()
 
-    def on_log(self, trainer: BaseTrainer, records: dict, dry_run: bool = False):
+    def on_log_scalars(
+        self, trainer: BaseTrainer, records: dict, dry_run: bool = False
+    ):
         if _dist_rank() == 0:
             data = {"/".join(k): v for k, v in flatten_nested_dict(records).items()}
             if not dry_run:
@@ -748,6 +759,10 @@ class WandbHook(BaseHook):
 class TensorBoardHook(BaseHook):
     """Log metrics and images to TensorBoard (rank 0 only).
 
+    Nested namespace components are joined with ``namespace_separator`` and
+    the final name is separated with ``/``. Avoid these separators within
+    individual keys because TensorBoard uses them to organize tags.
+
     Args:
         texts: Optional text values to log when training starts.
         namespace_separator: Separator for nested tag prefixes; the final TensorBoard
@@ -784,7 +799,9 @@ class TensorBoardHook(BaseHook):
         self.writer.close()
         self.writer = None
 
-    def on_log(self, trainer: BaseTrainer, records: dict, dry_run: bool = False):
+    def on_log_scalars(
+        self, trainer: BaseTrainer, records: dict, dry_run: bool = False
+    ):
         if self.writer is None:
             return
 

{trainloop-0.9.0 → trainloop-0.11.0}/src/trainloop/trainer.py

@@ -349,17 +349,22 @@ class BaseTrainer:
     def unwrapped_model(self):
         return self.unwrap(self.model)
 
-    def log(self, records: dict[str, Any], dry_run: bool = False):
+    def log_scalars(self, records: dict[str, Any], dry_run: bool = False):
         """
-        Dispatch numeric records to hooks (e.g., trackers or stdout).
+        Dispatch nested scalar records to logging hooks.
+
+        Dictionary keys are treated as path components. Logging hooks may join
+        nested components with backend-specific namespace separators, such as
+        ``/``. Avoid those separators within individual keys because distinct
+        nested paths may otherwise map to the same backend metric name.
 
         Args:
-            records: Nested dict of numeric metrics to log.
+            records: Nested dict of scalar metrics to log.
             dry_run: If True, hooks should avoid side effects and only report intent.
         """
-        self.logger.debug("log()")
+        self.logger.debug("log_scalars()")
         for h in self.hooks:
-            h.on_log(self, records, dry_run=dry_run)
+            h.on_log_scalars(self, records, dry_run=dry_run)
 
     def log_images(self, records: dict[str, Any], dry_run: bool = False):
         """