torchlight 0.1.0__py3-none-any.whl

torchlight/__init__.py

@@ -0,0 +1,28 @@
+"""torchlight: a lightweight companion for PyTorch training loops."""
+
+from .callbacks import Callback, EarlyStopping, ModelCheckpoint, PrintLogger
+from .checkpoint import load_checkpoint, save_checkpoint
+from .metrics import Accuracy, Mean, MeanAbsoluteError, Metric
+from .trainer import Trainer
+from .utils import count_parameters, get_device, seed_everything, to_device
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Trainer",
+    "Callback",
+    "EarlyStopping",
+    "ModelCheckpoint",
+    "PrintLogger",
+    "Metric",
+    "Mean",
+    "Accuracy",
+    "MeanAbsoluteError",
+    "save_checkpoint",
+    "load_checkpoint",
+    "seed_everything",
+    "get_device",
+    "to_device",
+    "count_parameters",
+    "__version__",
+]

torchlight/callbacks.py

@@ -0,0 +1,183 @@
+"""Callbacks that hook into :meth:`torchlight.Trainer.fit`."""
+
+from __future__ import annotations
+
+import copy
+import math
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from .checkpoint import save_checkpoint
+
+if TYPE_CHECKING:
+    from .trainer import Trainer
+
+__all__ = ["Callback", "EarlyStopping", "ModelCheckpoint", "PrintLogger"]
+
+Mode = Literal["min", "max"]
+
+
+class Callback:
+    """Base class for callbacks. Override any subset of the hooks.
+
+    ``logs`` passed to :meth:`on_epoch_end` is the dict of epoch results, e.g.
+    ``{"loss": 0.31, "accuracy": 0.9, "val_loss": 0.35, "val_accuracy": 0.88}``.
+    Set ``trainer.should_stop = True`` to end training after the current epoch.
+    """
+
+    def on_fit_start(self, trainer: Trainer) -> None:
+        """Called once before the first epoch."""
+
+    def on_epoch_start(self, trainer: Trainer, epoch: int) -> None:
+        """Called before each epoch (``epoch`` is 0-based)."""
+
+    def on_batch_end(self, trainer: Trainer, batch_idx: int, loss: float) -> None:
+        """Called after each training step with that batch's loss."""
+
+    def on_epoch_end(self, trainer: Trainer, epoch: int, logs: dict[str, float]) -> None:
+        """Called after training (and validation, if any) for each epoch."""
+
+    def on_fit_end(self, trainer: Trainer) -> None:
+        """Called once after the last epoch, including after an early stop."""
+
+
+def _monitored(logs: dict[str, float], monitor: str, owner: str) -> float:
+    if monitor not in logs:
+        raise KeyError(
+            f"{owner}: monitored key {monitor!r} not in epoch logs "
+            f"(available: {sorted(logs)})"
+        )
+    return logs[monitor]
+
+
+def _improved(current: float, best: float, mode: Mode, min_delta: float) -> bool:
+    if mode == "min":
+        return current < best - min_delta
+    return current > best + min_delta
+
+
+def _check_mode(mode: str) -> None:
+    if mode not in ("min", "max"):
+        raise ValueError(f"mode must be 'min' or 'max', got {mode!r}")
+
+
+class EarlyStopping(Callback):
+    """Stop training when a monitored value stops improving.
+
+    Args:
+        monitor: Key in the epoch logs to watch, e.g. ``"val_loss"``.
+        patience: Epochs without improvement to tolerate before stopping.
+        mode: ``"min"`` if lower is better, ``"max"`` if higher is better.
+        min_delta: Minimum change that counts as an improvement.
+        restore_best_weights: On stop (or fit end), load the weights from the
+            best epoch back into the model.
+    """
+
+    def __init__(
+        self,
+        monitor: str = "val_loss",
+        patience: int = 3,
+        mode: Mode = "min",
+        min_delta: float = 0.0,
+        restore_best_weights: bool = False,
+    ) -> None:
+        _check_mode(mode)
+        self.monitor = monitor
+        self.patience = patience
+        self.mode: Mode = mode
+        self.min_delta = min_delta
+        self.restore_best_weights = restore_best_weights
+        self.best: float = math.inf if mode == "min" else -math.inf
+        self.best_epoch: int = -1
+        self.wait = 0
+        self.stopped_epoch: int | None = None
+        self._best_state: dict[str, Any] | None = None
+
+    def on_fit_start(self, trainer: Trainer) -> None:
+        self.best = math.inf if self.mode == "min" else -math.inf
+        self.best_epoch = -1
+        self.wait = 0
+        self.stopped_epoch = None
+        self._best_state = None
+
+    def on_epoch_end(self, trainer: Trainer, epoch: int, logs: dict[str, float]) -> None:
+        current = _monitored(logs, self.monitor, "EarlyStopping")
+        if _improved(current, self.best, self.mode, self.min_delta):
+            self.best = current
+            self.best_epoch = epoch
+            self.wait = 0
+            if self.restore_best_weights:
+                self._best_state = copy.deepcopy(trainer.model.state_dict())
+            return
+        self.wait += 1
+        if self.wait >= self.patience:
+            self.stopped_epoch = epoch
+            trainer.should_stop = True
+
+    def on_fit_end(self, trainer: Trainer) -> None:
+        if self.restore_best_weights and self._best_state is not None:
+            trainer.model.load_state_dict(self._best_state)
+
+
+class ModelCheckpoint(Callback):
+    """Save a checkpoint at the end of epochs.
+
+    Args:
+        path: File to write. May contain ``{epoch}`` and any log key as format
+            fields, e.g. ``"ckpt/epoch{epoch:02d}-{val_loss:.3f}.pt"``.
+        monitor: Key in the epoch logs used to decide what is "best".
+        mode: ``"min"`` or ``"max"``.
+        save_best_only: If True, only write when ``monitor`` improves;
+            otherwise write every epoch.
+
+    After fitting, :attr:`best_path` holds the last file written for the best
+    value (or the latest file when ``save_best_only`` is False).
+    """
+
+    def __init__(
+        self,
+        path: str | os.PathLike[str],
+        monitor: str = "val_loss",
+        mode: Mode = "min",
+        save_best_only: bool = True,
+    ) -> None:
+        _check_mode(mode)
+        self.path = str(path)
+        self.monitor = monitor
+        self.mode: Mode = mode
+        self.save_best_only = save_best_only
+        self.best: float = math.inf if mode == "min" else -math.inf
+        self.best_path: Path | None = None
+
+    def on_fit_start(self, trainer: Trainer) -> None:
+        self.best = math.inf if self.mode == "min" else -math.inf
+        self.best_path = None
+
+    def on_epoch_end(self, trainer: Trainer, epoch: int, logs: dict[str, float]) -> None:
+        current = _monitored(logs, self.monitor, "ModelCheckpoint")
+        improved = _improved(current, self.best, self.mode, 0.0)
+        if self.save_best_only and not improved:
+            return
+        if improved:
+            self.best = current
+        target = self.path.format(epoch=epoch, **logs)
+        self.best_path = save_checkpoint(
+            target,
+            trainer.model,
+            trainer.optimizer,
+            epoch=epoch,
+            logs=dict(logs),
+        )
+
+
+class PrintLogger(Callback):
+    """Print one line of epoch results, e.g. ``epoch 3/10  loss=0.1234 ...``."""
+
+    def __init__(self, precision: int = 4) -> None:
+        self.precision = precision
+
+    def on_epoch_end(self, trainer: Trainer, epoch: int, logs: dict[str, float]) -> None:
+        parts = "  ".join(f"{k}={v:.{self.precision}f}" for k, v in logs.items())
+        total = trainer.epochs if trainer.epochs is not None else "?"
+        print(f"epoch {epoch + 1}/{total}  {parts}")

torchlight/checkpoint.py

@@ -0,0 +1,70 @@
+"""Saving and restoring model/optimizer state."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import torch
+from torch import nn
+
+__all__ = ["save_checkpoint", "load_checkpoint"]
+
+
+def save_checkpoint(
+    path: str | os.PathLike[str],
+    model: nn.Module,
+    optimizer: torch.optim.Optimizer | None = None,
+    **extra: Any,
+) -> Path:
+    """Write a checkpoint dictionary to ``path``.
+
+    The file holds ``{"model": state_dict, "optimizer": state_dict | None,
+    **extra}``. Parent directories are created as needed.
+
+    Args:
+        path: Destination file.
+        model: Model whose ``state_dict`` is saved.
+        optimizer: Optional optimizer whose ``state_dict`` is saved.
+        **extra: Additional picklable values, e.g. ``epoch=3``.
+
+    Returns:
+        The path written, as a :class:`~pathlib.Path`.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload: dict[str, Any] = {
+        "model": model.state_dict(),
+        "optimizer": optimizer.state_dict() if optimizer is not None else None,
+        **extra,
+    }
+    torch.save(payload, path)
+    return path
+
+
+def load_checkpoint(
+    path: str | os.PathLike[str],
+    model: nn.Module,
+    optimizer: torch.optim.Optimizer | None = None,
+    map_location: str | torch.device = "cpu",
+) -> dict[str, Any]:
+    """Restore state written by :func:`save_checkpoint`.
+
+    Args:
+        path: Checkpoint file.
+        model: Model to load weights into (in place).
+        optimizer: If given and the checkpoint contains optimizer state, it is
+            loaded too.
+        map_location: Passed to :func:`torch.load`.
+
+    Returns:
+        The full checkpoint dictionary, so callers can read ``extra`` values.
+    """
+    checkpoint: dict[str, Any] = torch.load(
+        Path(path), map_location=map_location, weights_only=True
+    )
+    model.load_state_dict(checkpoint["model"])
+    if optimizer is not None and checkpoint.get("optimizer") is not None:
+        optimizer.load_state_dict(checkpoint["optimizer"])
+    return checkpoint

torchlight/metrics.py

@@ -0,0 +1,109 @@
+"""Stateful, accumulate-then-compute metrics."""
+
+from __future__ import annotations
+
+import torch
+
+__all__ = ["Metric", "Mean", "Accuracy", "MeanAbsoluteError"]
+
+
+class Metric:
+    """Base class for metrics accumulated over batches.
+
+    Subclasses implement :meth:`update`, :meth:`compute` and :meth:`reset`.
+    The :class:`~torchlight.Trainer` calls ``reset()`` at the start of each
+    epoch, ``update(outputs, targets)`` after each batch, and ``compute()`` at
+    the end of the epoch.
+    """
+
+    def update(self, preds: torch.Tensor, targets: torch.Tensor) -> None:
+        """Accumulate statistics for one batch."""
+        raise NotImplementedError
+
+    def compute(self) -> float:
+        """Return the metric value over everything seen since the last reset."""
+        raise NotImplementedError
+
+    def reset(self) -> None:
+        """Clear accumulated state."""
+        raise NotImplementedError
+
+
+class Mean:
+    """Weighted running mean of scalar values (used for the epoch loss)."""
+
+    def __init__(self) -> None:
+        self.reset()
+
+    def update(self, value: float, weight: int = 1) -> None:
+        """Add ``value`` with the given ``weight`` (e.g. the batch size)."""
+        self._total += float(value) * weight
+        self._count += weight
+
+    def compute(self) -> float:
+        """Return the mean, or ``nan`` if nothing has been added."""
+        return self._total / self._count if self._count else float("nan")
+
+    def reset(self) -> None:
+        """Clear accumulated state."""
+        self._total = 0.0
+        self._count = 0
+
+
+class Accuracy(Metric):
+    """Classification accuracy.
+
+    * If ``preds`` has one more dimension than ``targets`` (e.g. logits of
+      shape ``(N, C)`` against labels of shape ``(N,)``), the predicted class
+      is ``preds.argmax(dim=1)``.
+    * If shapes match (binary case), a prediction is positive when
+      ``preds >= threshold``. Pass probabilities, or set ``threshold=0.0`` for
+      raw logits.
+    """
+
+    def __init__(self, threshold: float = 0.5) -> None:
+        self.threshold = threshold
+        self.reset()
+
+    def update(self, preds: torch.Tensor, targets: torch.Tensor) -> None:
+        if preds.dim() == targets.dim() + 1:
+            predicted = preds.argmax(dim=1)
+        elif preds.shape == targets.shape:
+            predicted = (preds >= self.threshold).to(targets.dtype)
+        else:
+            raise ValueError(
+                f"Accuracy: incompatible shapes preds={tuple(preds.shape)} "
+                f"targets={tuple(targets.shape)}"
+            )
+        self._correct += int((predicted == targets).sum().item())
+        self._total += targets.numel()
+
+    def compute(self) -> float:
+        return self._correct / self._total if self._total else float("nan")
+
+    def reset(self) -> None:
+        self._correct = 0
+        self._total = 0
+
+
+class MeanAbsoluteError(Metric):
+    """Mean absolute error for regression outputs."""
+
+    def __init__(self) -> None:
+        self.reset()
+
+    def update(self, preds: torch.Tensor, targets: torch.Tensor) -> None:
+        if preds.shape != targets.shape:
+            raise ValueError(
+                f"MeanAbsoluteError: shape mismatch preds={tuple(preds.shape)} "
+                f"targets={tuple(targets.shape)}"
+            )
+        self._abs_sum += float((preds.detach() - targets).abs().sum().item())
+        self._count += targets.numel()
+
+    def compute(self) -> float:
+        return self._abs_sum / self._count if self._count else float("nan")
+
+    def reset(self) -> None:
+        self._abs_sum = 0.0
+        self._count = 0

torchlight/trainer.py

@@ -0,0 +1,195 @@
+"""A minimal, explicit training loop."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from typing import Any
+
+import torch
+from torch import nn
+
+from .callbacks import Callback
+from .metrics import Mean, Metric
+from .utils import get_device, to_device
+
+__all__ = ["Trainer"]
+
+Batch = Any
+LossFn = Callable[[torch.Tensor, torch.Tensor], torch.Tensor]
+
+
+class Trainer:
+    """Train, evaluate and predict with a ``torch.nn.Module``.
+
+    Each batch from a data loader must be an ``(inputs, targets)`` pair, where
+    ``inputs`` is passed straight to ``model(inputs)``. ``inputs`` and
+    ``targets`` may be tensors or nested lists/tuples/dicts of tensors; they
+    are moved to :attr:`device` automatically. For :meth:`predict`, a batch may
+    also be bare ``inputs``.
+
+    Args:
+        model: The model to train. It is moved to ``device``.
+        optimizer: Optimizer over the model's parameters.
+        loss_fn: Callable ``loss_fn(outputs, targets) -> scalar tensor``.
+        metrics: Mapping of name to :class:`~torchlight.metrics.Metric`,
+            reported for training and (prefixed ``val_``) validation.
+        callbacks: Callbacks invoked during :meth:`fit`.
+        device: Device to run on; defaults to :func:`~torchlight.get_device`.
+        grad_clip: If set, clip the global gradient norm to this value.
+
+    Attributes:
+        history: Per-epoch values for every log key, e.g.
+            ``trainer.history["val_loss"]``.
+        should_stop: Set to True (typically by a callback) to stop
+            :meth:`fit` after the current epoch.
+        epochs: Number of epochs requested by the running/last :meth:`fit`.
+    """
+
+    def __init__(
+        self,
+        model: nn.Module,
+        optimizer: torch.optim.Optimizer,
+        loss_fn: LossFn,
+        metrics: Mapping[str, Metric] | None = None,
+        callbacks: Sequence[Callback] | None = None,
+        device: str | torch.device | None = None,
+        grad_clip: float | None = None,
+    ) -> None:
+        self.device = get_device(device)
+        self.model = model.to(self.device)
+        self.optimizer = optimizer
+        self.loss_fn = loss_fn
+        self.metrics: dict[str, Metric] = dict(metrics or {})
+        self.callbacks: list[Callback] = list(callbacks or [])
+        self.grad_clip = grad_clip
+        self.history: dict[str, list[float]] = {}
+        self.should_stop = False
+        self.epochs: int | None = None
+
+    # ------------------------------------------------------------------ fit
+    def fit(
+        self,
+        train_loader: Iterable[Batch],
+        val_loader: Iterable[Batch] | None = None,
+        epochs: int = 1,
+    ) -> dict[str, list[float]]:
+        """Train for up to ``epochs`` epochs.
+
+        Logged keys per epoch are ``loss`` and each metric name, plus
+        ``val_loss`` and ``val_<metric>`` when ``val_loader`` is given.
+
+        Returns:
+            :attr:`history`, mapping each log key to its per-epoch values.
+        """
+        if epochs < 1:
+            raise ValueError(f"epochs must be >= 1, got {epochs}")
+        self.epochs = epochs
+        self.should_stop = False
+        self.history = {}
+        self._call("on_fit_start")
+        for epoch in range(epochs):
+            self._call("on_epoch_start", epoch)
+            logs = self._train_epoch(train_loader)
+            if val_loader is not None:
+                val = self.evaluate(val_loader)
+                logs.update({f"val_{k}": v for k, v in val.items()})
+            for key, value in logs.items():
+                self.history.setdefault(key, []).append(value)
+            self._call("on_epoch_end", epoch, logs)
+            if self.should_stop:
+                break
+        self._call("on_fit_end")
+        return self.history
+
+    def _train_epoch(self, loader: Iterable[Batch]) -> dict[str, float]:
+        self.model.train()
+        loss_mean = Mean()
+        self._reset_metrics()
+        for batch_idx, batch in enumerate(loader):
+            inputs, targets = self._split(batch)
+            self.optimizer.zero_grad(set_to_none=True)
+            outputs = self.model(inputs)
+            loss = self.loss_fn(outputs, targets)
+            loss.backward()
+            if self.grad_clip is not None:
+                nn.utils.clip_grad_norm_(self.model.parameters(), self.grad_clip)
+            self.optimizer.step()
+
+            loss_value = float(loss.detach().item())
+            loss_mean.update(loss_value, _batch_size(targets))
+            self._update_metrics(outputs.detach(), targets)
+            self._call("on_batch_end", batch_idx, loss_value)
+        return {"loss": loss_mean.compute(), **self._compute_metrics()}
+
+    # ------------------------------------------------------------- evaluate
+    @torch.no_grad()
+    def evaluate(self, loader: Iterable[Batch]) -> dict[str, float]:
+        """Compute loss and metrics on ``loader`` without updating weights.
+
+        Returns:
+            ``{"loss": ..., <metric name>: ...}`` (no ``val_`` prefix).
+        """
+        self.model.eval()
+        loss_mean = Mean()
+        self._reset_metrics()
+        for batch in loader:
+            inputs, targets = self._split(batch)
+            outputs = self.model(inputs)
+            loss = self.loss_fn(outputs, targets)
+            loss_mean.update(float(loss.item()), _batch_size(targets))
+            self._update_metrics(outputs, targets)
+        return {"loss": loss_mean.compute(), **self._compute_metrics()}
+
+    # -------------------------------------------------------------- predict
+    @torch.no_grad()
+    def predict(self, loader: Iterable[Batch]) -> torch.Tensor:
+        """Run the model over ``loader`` and concatenate outputs on the CPU.
+
+        Each batch may be ``(inputs, targets)`` (targets are ignored) or bare
+        ``inputs``. The model must return a tensor.
+        """
+        self.model.eval()
+        outputs: list[torch.Tensor] = []
+        for batch in loader:
+            if isinstance(batch, (list, tuple)) and len(batch) == 2:
+                batch = batch[0]
+            outputs.append(self.model(to_device(batch, self.device)).cpu())
+        if not outputs:
+            raise ValueError("predict() received an empty loader")
+        return torch.cat(outputs, dim=0)
+
+    # -------------------------------------------------------------- helpers
+    def _split(self, batch: Batch) -> tuple[Any, Any]:
+        if not (isinstance(batch, (list, tuple)) and len(batch) == 2):
+            raise TypeError(
+                "Each batch must be an (inputs, targets) pair; "
+                f"got {type(batch).__name__}"
+            )
+        inputs, targets = batch
+        return to_device(inputs, self.device), to_device(targets, self.device)
+
+    def _reset_metrics(self) -> None:
+        for metric in self.metrics.values():
+            metric.reset()
+
+    def _update_metrics(self, outputs: torch.Tensor, targets: torch.Tensor) -> None:
+        for metric in self.metrics.values():
+            metric.update(outputs, targets)
+
+    def _compute_metrics(self) -> dict[str, float]:
+        return {name: metric.compute() for name, metric in self.metrics.items()}
+
+    def _call(self, hook: str, *args: Any) -> None:
+        for callback in self.callbacks:
+            getattr(callback, hook)(self, *args)
+
+
+def _batch_size(targets: Any) -> int:
+    """Best-effort batch size used to weight the per-batch loss."""
+    if isinstance(targets, torch.Tensor) and targets.dim() > 0:
+        return int(targets.shape[0])
+    if isinstance(targets, (list, tuple)) and targets:
+        return _batch_size(targets[0])
+    if isinstance(targets, Mapping) and targets:
+        return _batch_size(next(iter(targets.values())))
+    return 1

torchlight/utils.py

@@ -0,0 +1,87 @@
+"""Small helpers for reproducibility, device selection and moving data around."""
+
+from __future__ import annotations
+
+import os
+import random
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import torch
+from torch import nn
+
+__all__ = ["seed_everything", "get_device", "to_device", "count_parameters"]
+
+
+def seed_everything(seed: int, deterministic: bool = False) -> int:
+    """Seed Python, NumPy (if installed) and PyTorch RNGs.
+
+    Args:
+        seed: The seed value.
+        deterministic: If True, also ask PyTorch to use deterministic
+            algorithms (may be slower, and raises on ops that have none).
+
+    Returns:
+        The seed that was applied, for convenient logging.
+    """
+    random.seed(seed)
+    os.environ["PYTHONHASHSEED"] = str(seed)
+    try:
+        import numpy as np
+
+        np.random.seed(seed)
+    except ImportError:  # NumPy is optional
+        pass
+    torch.manual_seed(seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(seed)
+    if deterministic:
+        torch.use_deterministic_algorithms(True)
+        torch.backends.cudnn.benchmark = False
+    return seed
+
+
+def get_device(prefer: str | torch.device | None = None) -> torch.device:
+    """Return a ``torch.device``.
+
+    Args:
+        prefer: An explicit device (e.g. ``"cpu"``, ``"cuda:1"``). If omitted,
+            picks CUDA, then Apple MPS, then CPU, whichever is available first.
+    """
+    if prefer is not None:
+        return torch.device(prefer)
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    mps = getattr(torch.backends, "mps", None)
+    if mps is not None and mps.is_available():
+        return torch.device("mps")
+    return torch.device("cpu")
+
+
+def to_device(data: Any, device: str | torch.device) -> Any:
+    """Recursively move tensors in ``data`` to ``device``.
+
+    Handles tensors, mappings, lists and tuples (including named tuples).
+    Any other object is returned unchanged.
+    """
+    if isinstance(data, torch.Tensor):
+        return data.to(device)
+    if isinstance(data, Mapping):
+        return type(data)({k: to_device(v, device) for k, v in data.items()})  # type: ignore[call-arg]
+    if isinstance(data, tuple) and hasattr(data, "_fields"):  # named tuple
+        return type(data)(*(to_device(v, device) for v in data))
+    if isinstance(data, Sequence) and not isinstance(data, (str, bytes)):
+        return type(data)(to_device(v, device) for v in data)  # type: ignore[call-arg]
+    return data
+
+
+def count_parameters(model: nn.Module, trainable_only: bool = True) -> int:
+    """Count the parameters of ``model``.
+
+    Args:
+        model: The module to inspect.
+        trainable_only: Count only parameters with ``requires_grad=True``.
+    """
+    return sum(
+        p.numel() for p in model.parameters() if p.requires_grad or not trainable_only
+    )

torchlight-0.1.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: torchlight
+Version: 0.1.0
+Summary: Torch Light: a lightweight PyTorch companion with a minimal Trainer, callbacks, metrics and checkpointing.
+Author: nehz
+License: MIT
+License-File: LICENSE
+Keywords: deep-learning,pytorch,torch,trainer,training
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: torch>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# torchlight
+
+**Torch Light**: a lightweight companion for PyTorch.
+
+`torchlight` gives you a small, readable training loop plus the extras you end
+up rewriting in every project: callbacks, metrics, early stopping,
+checkpointing and seeding/device helpers. It is a few hundred lines of plain
+PyTorch with no other dependencies, so you can read all of it in one sitting.
+When you outgrow it, copy the parts you need.
+
+## Features
+
+- **`Trainer`**: `fit` / `evaluate` / `predict` over any iterable of
+  `(inputs, targets)` batches, with automatic device placement (including
+  nested dicts, lists and tuples), optional gradient-norm clipping, and a
+  per-epoch `history`.
+- **Callbacks**: hook into fit start, epoch start, batch end, epoch end and
+  fit end. Built in: `EarlyStopping` (with `restore_best_weights`),
+  `ModelCheckpoint` (best-only or every epoch, templated filenames), and
+  `PrintLogger`.
+- **Metrics**: accumulate-then-compute `Accuracy` (multi-class logits or
+  binary thresholds) and `MeanAbsoluteError`. Subclass `Metric` to add your own.
+- **Checkpoints**: `save_checkpoint` / `load_checkpoint` for model and
+  optimizer state plus any extra values.
+- **Utilities**: `seed_everything`, `get_device`, `to_device`,
+  `count_parameters`.
+
+## Install
+
+```bash
+pip install torchlight
+```
+
+`torch>=2.0` is the only dependency. To use the CPU-only PyTorch build, install
+it first, for example
+`pip install torch --index-url https://download.pytorch.org/whl/cpu`.
+
+From a source checkout:
+
+```bash
+python -m venv .venv
+.venv/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu
+.venv/bin/pip install -e ".[test]"
+.venv/bin/python -m pytest
+```
+
+## Quickstart
+
+```python
+import torch
+from torch import nn
+from torch.utils.data import DataLoader, TensorDataset
+
+import torchlight as tl
+
+tl.seed_everything(42)
+
+# Synthetic two-class data
+x = torch.randn(512, 2)
+y = (x[:, 0] + x[:, 1] > 0).long()
+train = DataLoader(TensorDataset(x[:400], y[:400]), batch_size=32, shuffle=True)
+val = DataLoader(TensorDataset(x[400:], y[400:]), batch_size=64)
+
+model = nn.Sequential(nn.Linear(2, 16), nn.ReLU(), nn.Linear(16, 2))
+trainer = tl.Trainer(
+    model,
+    optimizer=torch.optim.Adam(model.parameters(), lr=1e-2),
+    loss_fn=nn.CrossEntropyLoss(),
+    metrics={"accuracy": tl.Accuracy()},
+    callbacks=[
+        tl.EarlyStopping(monitor="val_loss", patience=3, restore_best_weights=True),
+        tl.ModelCheckpoint("checkpoints/best.pt", monitor="val_accuracy", mode="max"),
+        tl.PrintLogger(),
+    ],
+)
+
+history = trainer.fit(train, val, epochs=20)
+print(history["val_accuracy"][-1])
+
+print(trainer.evaluate(val))        # {'loss': ..., 'accuracy': ...}
+probs = trainer.predict(val).softmax(dim=1)
+
+# Later: restore the best checkpoint
+ckpt = tl.load_checkpoint("checkpoints/best.pt", model)
+print(ckpt["epoch"], ckpt["logs"])
+```
+
+## API overview
+
+Everything below is importable from the top-level `torchlight` package.
+
+### `Trainer`
+
+```python
+Trainer(model, optimizer, loss_fn, metrics=None, callbacks=None, device=None, grad_clip=None)
+```
+
+| Member | Description |
+| --- | --- |
+| `fit(train_loader, val_loader=None, epochs=1) -> dict[str, list[float]]` | Train for up to `epochs` epochs and return `history`. Logs `loss` and each metric name; with `val_loader`, also `val_loss` and `val_<metric>`. |
+| `evaluate(loader) -> dict[str, float]` | Loss and metrics under `torch.no_grad()`, in eval mode, with no `val_` prefix. |
+| `predict(loader) -> torch.Tensor` | Model outputs concatenated on the CPU. Batches may be `(inputs, targets)` or bare `inputs`. |
+| `history` | `dict[str, list[float]]` of per-epoch values. |
+| `should_stop` | Set to `True` (usually from a callback) to stop after the current epoch. |
+| `model`, `optimizer`, `loss_fn`, `metrics`, `callbacks`, `device`, `grad_clip`, `epochs` | The configured objects. `epochs` is the value passed to the latest `fit`. |
+
+Batches must be `(inputs, targets)` pairs. `inputs` goes straight to
+`model(inputs)`, and both halves are moved to `trainer.device`. The loss is
+averaged over samples, with each batch weighted by its size. `device`
+defaults to `get_device()`.
+
+### Callbacks
+
+```python
+class Callback:
+    def on_fit_start(self, trainer): ...
+    def on_epoch_start(self, trainer, epoch): ...           # epoch is 0-based
+    def on_batch_end(self, trainer, batch_idx, loss): ...   # loss is a float
+    def on_epoch_end(self, trainer, epoch, logs): ...       # logs: dict[str, float]
+    def on_fit_end(self, trainer): ...                      # also runs after an early stop
+```
+
+- `EarlyStopping(monitor="val_loss", patience=3, mode="min", min_delta=0.0, restore_best_weights=False)`
+  sets `trainer.should_stop` after `patience` epochs without improvement.
+  Attributes: `best`, `best_epoch`, `wait`, `stopped_epoch`.
+- `ModelCheckpoint(path, monitor="val_loss", mode="min", save_best_only=True)`
+  writes `save_checkpoint(path, model, optimizer, epoch=..., logs=...)`.
+  `path` may use `{epoch}` and any log key as format fields, e.g.
+  `"ckpt/ep{epoch:02d}-{val_loss:.3f}.pt"`. Attributes: `best`, `best_path`.
+- `PrintLogger(precision=4)` prints `epoch 3/10  loss=0.1234  val_loss=...`.
+
+If a monitored key is missing from the epoch logs (for example `val_loss`
+without a `val_loader`), the callback raises `KeyError`.
+
+### Metrics
+
+```python
+class Metric:
+    def update(self, preds, targets) -> None: ...
+    def compute(self) -> float: ...
+    def reset(self) -> None: ...
+```
+
+- `Accuracy(threshold=0.5)`: uses `argmax(dim=1)` when `preds` has one more
+  dimension than `targets`. Otherwise `preds >= threshold`; use
+  `threshold=0.0` for raw binary logits.
+- `MeanAbsoluteError()`: `preds` and `targets` must have the same shape.
+- `Mean()`: weighted running mean, `update(value, weight=1)`. The trainer uses
+  it for the loss.
+
+`compute()` returns `nan` if nothing has been accumulated.
+
+### Checkpoints
+
+- `save_checkpoint(path, model, optimizer=None, **extra) -> pathlib.Path`
+  saves `{"model": ..., "optimizer": ... or None, **extra}` and creates
+  parent directories.
+- `load_checkpoint(path, model, optimizer=None, map_location="cpu") -> dict`
+  loads weights (and optimizer state, if both are present) in place and
+  returns the full dict. It uses `torch.load(..., weights_only=True)`.
+
+### Utilities
+
+- `seed_everything(seed, deterministic=False) -> int` seeds `random`, NumPy
+  (if installed) and torch (CPU and CUDA).
+- `get_device(prefer=None) -> torch.device` returns `prefer` if given,
+  otherwise the first available of CUDA, MPS and CPU.
+- `to_device(data, device)` recursively moves tensors in dicts, lists, tuples
+  and named tuples.
+- `count_parameters(model, trainable_only=True) -> int`.
+
+## License
+
+MIT

torchlight-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+torchlight/__init__.py,sha256=D82Nv0gGD_nRdNtVCd8g9KkRXPVFqZqiunGdbuK3gc4,719
+torchlight/callbacks.py,sha256=o9w-ylhbe2L4vab8rW5oGWjvyhGpGw5wzba9WsBUL1A,6533
+torchlight/checkpoint.py,sha256=QaC84FlJ3B-SvzPo-EU1wnqyxlC0DlArsLPfcID_GoE,2094
+torchlight/metrics.py,sha256=uLdWqdZBm7YRsjI8P2xp5uHXsh0gm1Ggv_3dDycNOh8,3591
+torchlight/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+torchlight/trainer.py,sha256=avnNDr1KWjcuvSqeXbpHOV0NUJMIiudbzaCj7tHwmYg,7731
+torchlight/utils.py,sha256=iZJEpS5lIOj2I9Gw5bIbaX3pVJtvgZLchPiJXI3QBP4,2866
+torchlight-0.1.0.dist-info/METADATA,sha256=19w2UwLqJfEAPYMF9Bev7fKUt0yVT0O2uX1h_TTQ6l4,7859
+torchlight-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+torchlight-0.1.0.dist-info/licenses/LICENSE,sha256=pAfYREEW9GAy7cnK20OXjDn7ofJahYny9GCuIZQTDAA,1061
+torchlight-0.1.0.dist-info/RECORD,,

torchlight-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

torchlight-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nehz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.