laco-lightning 1.0.0__py3-none-any.whl

laco/integrations/lightning/__init__.py

@@ -0,0 +1,34 @@
+"""PyTorch Lightning integration for laco.
+
+Provides:
+
+- :class:`LacoConfigCallback` — logs the resolved laco DictConfig to every
+  logger attached to the ``Trainer`` (W&B, TensorBoard, MLflow, CSV, …).
+- :func:`trainer` — build a ``lightning.Trainer`` from a laco DictConfig.
+- :func:`fit` — convenience wrapper that wires config logging and training
+  into a single call.
+
+Examples
+--------
+::
+
+    import laco
+    import laco.integrations.lightning as laco_lightning
+    import lightning as L
+
+    cfg = laco.load("configs/train.py")
+    model = laco.instantiate(cfg.model)
+
+    trainer = laco_lightning.trainer(cfg.trainer)
+    laco_lightning.fit(trainer, model, cfg=cfg, datamodule=dm)
+
+    # Or just attach the callback manually:
+    trainer = L.Trainer(callbacks=[laco_lightning.LacoConfigCallback(cfg)])
+"""
+
+from laco.integrations.lightning._core import LacoConfigCallback as LacoConfigCallback
+from laco.integrations.lightning._core import _bootstrap as _bootstrap
+from laco.integrations.lightning._core import fit as fit
+from laco.integrations.lightning._core import trainer as trainer
+
+__all__ = ["LacoConfigCallback", "fit", "trainer"]

laco/integrations/lightning/_core.py

@@ -0,0 +1,177 @@
+"""Implementation for laco-lightning."""
+
+from __future__ import annotations
+
+import typing
+
+if typing.TYPE_CHECKING:
+    import lightning
+    from omegaconf import DictConfig
+
+# Cache for the lazily-constructed Callback subclass so we only pay the
+# lightning import cost once (on first instantiation of LacoConfigCallback).
+_CallbackCls: type | None = None
+
+
+def _bootstrap() -> None:
+    """Register Lightning classes as ``@L.configurable`` targets.
+
+    Called automatically via the ``laco.plugins`` entry point when
+    ``laco-lightning`` is installed — no explicit import required.
+    Silently does nothing if ``lightning`` is not importable.
+    """
+    try:
+        import lightning as _L
+        from laco.language import configurable
+
+        configurable(_L.Trainer)
+        configurable(_L.LightningModule)
+        configurable(_L.LightningDataModule)
+    except ImportError:
+        pass
+
+
+def _make_callback_cls() -> type:
+    global _CallbackCls  # noqa: PLW0603
+    if _CallbackCls is not None:
+        return _CallbackCls
+
+    from lightning.pytorch.callbacks import Callback  # type: ignore[import-untyped]
+    from omegaconf import OmegaConf
+
+    class _LacoConfigCallback(Callback):
+        """Logs the laco DictConfig to all Trainer loggers on fit start."""
+
+        def __init__(self, cfg: DictConfig) -> None:
+            super().__init__()
+            self.cfg = cfg
+
+        def on_fit_start(
+            self,
+            trainer: lightning.Trainer,
+            pl_module: lightning.LightningModule,
+        ) -> None:
+            flat = OmegaConf.to_container(
+                self.cfg, resolve=True, throw_on_missing=False
+            )
+            for logger in trainer.loggers:
+                if hasattr(logger, "log_hyperparams"):
+                    logger.log_hyperparams(flat)  # type: ignore[arg-type]
+
+    _LacoConfigCallback.__name__ = "LacoConfigCallback"
+    _LacoConfigCallback.__qualname__ = "LacoConfigCallback"
+    _CallbackCls = _LacoConfigCallback
+    return _CallbackCls
+
+
+class LacoConfigCallback:
+    """Lightning ``Callback`` that logs the laco config to all active loggers.
+
+    Runs on ``on_fit_start`` so the config is recorded before any training
+    step, regardless of which loggers are attached to the ``Trainer``.
+
+    Parameters
+    ----------
+    cfg : DictConfig
+        Resolved laco DictConfig to log as hyperparameters.
+
+    Examples
+    --------
+    ::
+
+        trainer = L.Trainer(
+            max_epochs=10,
+            callbacks=[laco_lightning.LacoConfigCallback(cfg)],
+        )
+    """
+
+    def __new__(cls, cfg: DictConfig) -> LacoConfigCallback:  # type: ignore[misc]
+        real_cls = _make_callback_cls()
+        instance = real_cls.__new__(real_cls)
+        instance.__init__(cfg)
+        return instance  # type: ignore[return-value]
+
+    def __init__(self, cfg: DictConfig) -> None:
+        self.cfg = cfg  # type: ignore[misc]
+
+
+def trainer(
+    cfg: DictConfig | None = None,
+    **kwargs: typing.Any,
+) -> lightning.Trainer:
+    """Build a ``lightning.Trainer`` from a laco DictConfig.
+
+    Fields in *cfg* are passed as keyword arguments to ``Trainer.__init__``.
+    Any *kwargs* are merged on top, letting call-site overrides win.
+
+    Parameters
+    ----------
+    cfg : DictConfig | None
+        Optional DictConfig whose keys map to ``Trainer`` constructor
+        parameters (``max_epochs``, ``accelerator``, ``devices``, …).
+    **kwargs
+        Additional ``Trainer`` kwargs that override *cfg* values.
+
+    Returns
+    -------
+    lightning.Trainer
+        Configured trainer instance.
+
+    Examples
+    --------
+    ::
+
+        t = laco_lightning.trainer(cfg.trainer_cfg, logger=my_logger)
+    """
+    import lightning as _L
+    from omegaconf import OmegaConf
+
+    params: dict[str, typing.Any] = {}
+    if cfg is not None:
+        params = dict(OmegaConf.to_container(cfg, resolve=True))  # type: ignore[arg-type]
+    params.update(kwargs)
+    return _L.Trainer(**params)
+
+
+def fit(
+    trainer: lightning.Trainer,
+    model: lightning.LightningModule,
+    *,
+    cfg: DictConfig,
+    log_config: bool = True,
+    **fit_kwargs: typing.Any,
+) -> None:
+    """Fit a Lightning model, optionally logging the laco config first.
+
+    Attaches a :class:`LacoConfigCallback` when *log_config* is ``True``
+    (the default), then calls ``trainer.fit(model, **fit_kwargs)``.
+
+    Parameters
+    ----------
+    trainer : lightning.Trainer
+        Configured ``Trainer`` instance.
+    model : lightning.LightningModule
+        ``LightningModule`` to train.
+    cfg : DictConfig
+        Resolved laco DictConfig — logged to all loggers if *log_config*
+        is ``True``.
+    log_config : bool
+        Whether to attach :class:`LacoConfigCallback`. Set to ``False`` if
+        you handle config logging yourself. Default: ``True``.
+    **fit_kwargs
+        Extra keyword arguments forwarded to ``trainer.fit()``
+        (e.g. ``datamodule``, ``train_dataloaders``, ``val_dataloaders``).
+
+    Examples
+    --------
+    ::
+
+        laco_lightning.fit(trainer, model, cfg=cfg, datamodule=dm)
+    """
+    if log_config:
+        callback = _make_callback_cls()(cfg)
+        if hasattr(trainer, "callbacks") and isinstance(trainer.callbacks, list):
+            trainer.callbacks.append(callback)
+        else:
+            trainer.callbacks = [callback]
+    trainer.fit(model, **fit_kwargs)

laco_lightning-1.0.0.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: laco-lightning
+Version: 1.0.0
+Summary: PyTorch Lightning integration for laco.
+Author-email: Kurt Stolle <kurt@khws.io>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: laco>=1.0.0
+Requires-Dist: lightning>=2.0
+
+# Laco-Lightning
+
+PyTorch Lightning integration for laco.
+
+Part of the [laco](https://github.com/khwstolle/laco) project — see the [root README](../../README.md) for an overview.
+
+## Installation
+
+```bash
+pip install laco-lightning
+```
+
+## Features
+
+`LacoConfigCallback`, `trainer()`, `fit()`
+
+## Usage
+
+See [`docs/index.md`](docs/index.md) for the full guide.

laco_lightning-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+laco/integrations/lightning/__init__.py,sha256=rmwiss6rzvka4z5JxNyb0mnIyuG8W8eSkDfBwxejjTg,1157
+laco/integrations/lightning/_core.py,sha256=z0SMDdrUmCu-TnS_LRuw7qNtd0FQlBXd5Nyl85W3t-A,5373
+laco_lightning-1.0.0.dist-info/METADATA,sha256=HuFLcRpOLaHLQ65Pfnc2lX-EtWAet-6xBw-Yt7ppPA0,633
+laco_lightning-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+laco_lightning-1.0.0.dist-info/entry_points.txt,sha256=owt1zWRxoMjOL-ydLbfOqZKf7tx59cOmWTemxN8mGHU,66
+laco_lightning-1.0.0.dist-info/top_level.txt,sha256=G2kLu09Aje44OkSqu-Tae3mjmTYhyRc2VrTyh3OmxFw,5
+laco_lightning-1.0.0.dist-info/RECORD,,

laco_lightning-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

laco_lightning-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[laco.plugins]
+lightning = laco.integrations.lightning:_bootstrap

laco_lightning-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+laco