laco-logging 1.0.0__py3-none-any.whl

laco/integrations/logging/__init__.py

@@ -0,0 +1,58 @@
+"""Unified experiment logging for laco.
+
+Supports Weights & Biases, MLflow, and TensorBoard through a common API.
+Each backend is an optional extra — install only what you need::
+
+    pip install laco-logging[wandb]
+    pip install laco-logging[mlflow]
+    pip install laco-logging[tensorboard]
+    pip install laco-logging[all]
+
+Top-level API
+-------------
+:func:`log_config`
+    Log a resolved DictConfig to one or more backends in a single call.
+
+:func:`run`
+    Unified context manager — delegates to the backend of your choice.
+
+Backend submodules
+------------------
+:mod:`laco.integrations.logging.wandb`
+    ``run(cfg, *, project, name, tags, ...)``
+    ``log_config(cfg, run=None)``
+
+:mod:`laco.integrations.logging.mlflow`
+    ``run(cfg, *, experiment, run_name, tags, ...)``
+    ``log_config(cfg, run_id=None)``
+    ``log_artifact(cfg)``
+
+:mod:`laco.integrations.logging.tensorboard`
+    ``run(cfg, *, log_dir, comment, ...)``
+    ``log_config(cfg, writer)``
+
+Examples
+--------
+::
+
+    import laco
+    import laco.integrations.logging as laco_logging
+
+    cfg = laco.load("configs/train.py")
+
+    # Single backend:
+    with laco_logging.run(cfg, backend="wandb", project="my-project") as run:
+        train(cfg)
+
+    # Multiple backends simultaneously:
+    laco_logging.log_config(cfg, backends=["wandb", "mlflow"])
+
+    # Backend submodule directly:
+    with laco_logging.tensorboard.run(cfg, log_dir="tb/run1") as writer:
+        writer.add_scalar("loss", 0.1, 0)
+"""
+
+from laco.integrations.logging._core import log_config as log_config
+from laco.integrations.logging._core import run as run
+
+__all__ = ["log_config", "mlflow", "run", "tensorboard", "wandb"]

laco/integrations/logging/_backends/__init__.py

@@ -0,0 +1 @@
+"""Backend implementations — imported lazily by the top-level API."""

laco/integrations/logging/_backends/mlflow.py

@@ -0,0 +1,69 @@
+"""MLflow backend for laco-logging."""
+
+from __future__ import annotations
+
+import contextlib
+import pathlib
+import typing
+
+if typing.TYPE_CHECKING:
+    import mlflow
+    from omegaconf import DictConfig
+
+
+def _flatten(d: dict, prefix: str = "") -> dict[str, str]:
+    out: dict[str, str] = {}
+    for k, v in d.items():
+        key = f"{prefix}.{k}" if prefix else k
+        if isinstance(v, dict):
+            out.update(_flatten(v, key))
+        else:
+            out[key] = str(v)
+    return out
+
+
+def log_config(cfg: DictConfig, run_id: str | None = None) -> None:
+    """Log *cfg* as MLflow params (flattened with dot-separated keys)."""
+    import mlflow as _mlflow
+    from omegaconf import OmegaConf
+
+    flat = OmegaConf.to_container(cfg, resolve=True, throw_on_missing=False)
+    params = _flatten(flat)  # type: ignore[arg-type]
+    if run_id:
+        with _mlflow.start_run(run_id=run_id):
+            _mlflow.log_params(params)
+    else:
+        _mlflow.log_params(params)
+
+
+def log_artifact(cfg: DictConfig) -> None:
+    """Save *cfg* as a ``config.yaml`` artifact in the active MLflow run."""
+    import tempfile
+
+    import mlflow as _mlflow
+    from omegaconf import OmegaConf
+
+    yaml_text = OmegaConf.to_yaml(cfg, resolve=True)
+    with tempfile.TemporaryDirectory() as tmp:
+        p = pathlib.Path(tmp) / "config.yaml"
+        p.write_text(yaml_text)
+        _mlflow.log_artifact(str(p))
+
+
+@contextlib.contextmanager
+def run(
+    cfg: DictConfig,
+    *,
+    experiment: str | None = None,
+    run_name: str | None = None,
+    tags: dict[str, str] | None = None,
+    **kwargs: typing.Any,
+) -> typing.Generator[mlflow.ActiveRun]:
+    """Start an MLflow run, log *cfg* as params, and end on exit."""
+    import mlflow as _mlflow
+
+    if experiment:
+        _mlflow.set_experiment(experiment)
+    with _mlflow.start_run(run_name=run_name, tags=tags, **kwargs) as active_run:
+        log_config(cfg, run_id=active_run.info.run_id)
+        yield active_run

laco/integrations/logging/_backends/tensorboard.py

@@ -0,0 +1,89 @@
+"""TensorBoard backend for laco-logging."""
+
+from __future__ import annotations
+
+import contextlib
+import typing
+
+if typing.TYPE_CHECKING:
+    from omegaconf import DictConfig
+    from torch.utils.tensorboard import SummaryWriter
+
+
+def log_config(cfg: DictConfig, writer: SummaryWriter) -> None:
+    """Log *cfg* as TensorBoard hparams with no associated metrics.
+
+    Writes a ``hparams`` entry to the TensorBoard event file so the
+    HParams dashboard shows the config alongside any scalars logged later.
+
+    Parameters
+    ----------
+    cfg : DictConfig
+        Resolved laco DictConfig.
+    writer : SummaryWriter
+        An open ``SummaryWriter``.
+    """
+    from omegaconf import OmegaConf
+
+    flat = OmegaConf.to_container(cfg, resolve=True, throw_on_missing=False)
+
+    def _flatten(d: dict, prefix: str = "") -> dict[str, typing.Any]:
+        out: dict[str, typing.Any] = {}
+        for k, v in d.items():
+            key = f"{prefix}.{k}" if prefix else k
+            if isinstance(v, dict):
+                out.update(_flatten(v, key))
+            elif isinstance(v, int | float | str | bool):
+                out[key] = v
+            else:
+                out[key] = str(v)
+        return out
+
+    hparams = _flatten(flat)  # type: ignore[arg-type]
+    # TensorBoard's add_hparams requires a metric_dict; pass an empty one
+    # so the hparams are visible without artificial metric entries.
+    writer.add_hparams(hparams, metric_dict={})
+
+
+@contextlib.contextmanager
+def run(
+    cfg: DictConfig,
+    *,
+    log_dir: str | None = None,
+    comment: str = "",
+    **kwargs: typing.Any,
+) -> typing.Generator[SummaryWriter]:
+    """Open a ``SummaryWriter``, log *cfg* as hparams, and close on exit.
+
+    Parameters
+    ----------
+    cfg : DictConfig
+        Resolved laco DictConfig.
+    log_dir : str | None
+        TensorBoard log directory. Defaults to ``runs/<timestamp>``.
+    comment : str
+        Appended to the auto-generated run name when *log_dir* is ``None``.
+    **kwargs
+        Extra kwargs forwarded to ``SummaryWriter.__init__``.
+
+    Yields
+    ------
+    SummaryWriter
+        An open ``torch.utils.tensorboard.SummaryWriter``.
+
+    Examples
+    --------
+    ::
+
+        with laco.integrations.logging.tensorboard.run(cfg, log_dir="tb_logs/run1") as writer:
+            for step, loss in enumerate(train(cfg)):
+                writer.add_scalar("loss/train", loss, step)
+    """
+    from torch.utils.tensorboard import SummaryWriter as _SW
+
+    writer = _SW(log_dir=log_dir, comment=comment, **kwargs)
+    log_config(cfg, writer)
+    try:
+        yield writer
+    finally:
+        writer.close()

laco/integrations/logging/_backends/wandb.py

@@ -0,0 +1,46 @@
+"""W&B backend for laco-logging."""
+
+from __future__ import annotations
+
+import contextlib
+import typing
+
+if typing.TYPE_CHECKING:
+    import wandb
+    from omegaconf import DictConfig
+
+
+def log_config(cfg: DictConfig, run: wandb.Run | None = None) -> None:
+    """Log *cfg* as W&B hyperparameters on *run* (or the global run)."""
+    import wandb as _wandb
+    from omegaconf import OmegaConf
+
+    target = run or _wandb.run
+    if target is None:
+        msg = "No active W&B run. Call wandb.init() before log_config()."
+        raise RuntimeError(msg)
+    flat = OmegaConf.to_container(cfg, resolve=True, throw_on_missing=False)
+    target.config.update(flat, allow_val_change=True)
+
+
+@contextlib.contextmanager
+def run(
+    cfg: DictConfig,
+    *,
+    project: str | None = None,
+    name: str | None = None,
+    tags: list[str] | None = None,
+    **kwargs: typing.Any,
+) -> typing.Generator[wandb.Run]:
+    """Start a W&B run, log *cfg*, and finish on exit."""
+    import wandb as _wandb
+    from omegaconf import OmegaConf
+
+    flat = OmegaConf.to_container(cfg, resolve=True, throw_on_missing=False)
+    wandb_run = _wandb.init(
+        project=project, name=name, tags=tags, config=flat, **kwargs
+    )
+    try:
+        yield wandb_run
+    finally:
+        wandb_run.finish()

laco/integrations/logging/_core.py

@@ -0,0 +1,94 @@
+"""Implementation for laco-logging."""
+
+from __future__ import annotations
+
+import contextlib
+import typing
+
+if typing.TYPE_CHECKING:
+    from omegaconf import DictConfig
+
+_BACKEND_MODULES = {
+    "wandb": "laco.integrations.logging._backends.wandb",
+    "mlflow": "laco.integrations.logging._backends.mlflow",
+    "tensorboard": "laco.integrations.logging._backends.tensorboard",
+}
+
+_Backend = typing.Literal["wandb", "mlflow", "tensorboard"]
+
+
+def log_config(
+    cfg: DictConfig,
+    backends: list[_Backend] | _Backend,
+    **backend_kwargs: typing.Any,
+) -> None:
+    """Log a resolved laco DictConfig to one or more backends.
+
+    Parameters
+    ----------
+    cfg : DictConfig
+        Resolved OmegaConf DictConfig from ``laco.load()``.
+    backends : str | list[str]
+        One backend name or a list of backend names.
+        Valid values: ``"wandb"``, ``"mlflow"``, ``"tensorboard"``.
+    **backend_kwargs
+        Passed through to each backend's ``log_config()``. For TensorBoard
+        a ``writer`` kwarg is required.
+
+    Raises
+    ------
+    ValueError
+        If an unknown backend name is provided.
+    """
+    import importlib
+
+    targets: list[_Backend] = [backends] if isinstance(backends, str) else backends
+    for backend in targets:
+        if backend not in _BACKEND_MODULES:
+            msg = f"Unknown backend {backend!r}. Choose from: {list(_BACKEND_MODULES)}"
+            raise ValueError(msg)
+        mod = importlib.import_module(_BACKEND_MODULES[backend])
+        mod.log_config(cfg, **backend_kwargs)
+
+
+@contextlib.contextmanager
+def run(
+    cfg: DictConfig,
+    *,
+    backend: _Backend,
+    **backend_kwargs: typing.Any,
+) -> typing.Generator[typing.Any]:
+    """Unified context manager — starts a run on the chosen backend.
+
+    Delegates entirely to the backend's own ``run()`` context manager,
+    forwarding all backend-specific kwargs unchanged.
+
+    Parameters
+    ----------
+    cfg : DictConfig
+        Resolved laco DictConfig.
+    backend : str
+        One of ``"wandb"``, ``"mlflow"``, ``"tensorboard"``.
+    **backend_kwargs
+        Forwarded to the backend's ``run()`` (e.g. ``project=`` for W&B,
+        ``experiment=`` for MLflow, ``log_dir=`` for TensorBoard).
+
+    Yields
+    ------
+    Any
+        The backend's run handle (``wandb.Run``, ``mlflow.ActiveRun``, or
+        ``torch.utils.tensorboard.SummaryWriter``).
+
+    Raises
+    ------
+    ValueError
+        If an unknown backend name is provided.
+    """
+    import importlib
+
+    if backend not in _BACKEND_MODULES:
+        msg = f"Unknown backend {backend!r}. Choose from: {list(_BACKEND_MODULES)}"
+        raise ValueError(msg)
+    mod = importlib.import_module(_BACKEND_MODULES[backend])
+    with mod.run(cfg, **backend_kwargs) as handle:
+        yield handle

laco/integrations/logging/mlflow.py

@@ -0,0 +1,7 @@
+"""MLflow backend — re-exported from laco.integrations.logging._backends.mlflow."""
+
+from laco.integrations.logging._backends.mlflow import log_artifact as log_artifact
+from laco.integrations.logging._backends.mlflow import log_config as log_config
+from laco.integrations.logging._backends.mlflow import run as run
+
+__all__ = ["log_artifact", "log_config", "run"]

laco/integrations/logging/tensorboard.py

@@ -0,0 +1,6 @@
+"""TensorBoard backend — re-exported from laco.integrations.logging._backends.tensorboard."""
+
+from laco.integrations.logging._backends.tensorboard import log_config as log_config
+from laco.integrations.logging._backends.tensorboard import run as run
+
+__all__ = ["log_config", "run"]

laco/integrations/logging/wandb.py

@@ -0,0 +1,6 @@
+"""W&B backend — re-exported from laco.integrations.logging._backends.wandb."""
+
+from laco.integrations.logging._backends.wandb import log_config as log_config
+from laco.integrations.logging._backends.wandb import run as run
+
+__all__ = ["log_config", "run"]

laco_logging-1.0.0.dist-info/METADATA

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: laco-logging
+Version: 1.0.0
+Summary: Unified experiment logging (W&B, MLflow, TensorBoard) for laco.
+Author-email: Kurt Stolle <kurt@khws.io>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: laco>=1.0.0
+Provides-Extra: wandb
+Requires-Dist: wandb>=0.19; extra == "wandb"
+Provides-Extra: mlflow
+Requires-Dist: mlflow>=2.0; extra == "mlflow"
+Provides-Extra: tensorboard
+Requires-Dist: tensorboard>=2.0; extra == "tensorboard"
+Provides-Extra: all
+Requires-Dist: wandb>=0.19; extra == "all"
+Requires-Dist: mlflow>=2.0; extra == "all"
+Requires-Dist: tensorboard>=2.0; extra == "all"
+
+# Laco-Logging
+
+Unified experiment logging (W&B, MLflow, TensorBoard) 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-logging[all]
+```
+
+## Extras
+
+| Extra | Installs |
+|---|---|
+| `laco-logging[wandb]` | W&B backend |
+| `laco-logging[mlflow]` | MLflow backend |
+| `laco-logging[tensorboard]` | TensorBoard backend |
+| `laco-logging[all]` | All backends |
+
+## Features
+
+`log_config()`, `run()`, submodules `wandb`, `mlflow`, `tensorboard`
+
+## Usage
+
+See [`docs/index.md`](docs/index.md) for the full guide.

laco_logging-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+laco/integrations/logging/__init__.py,sha256=lV4doaFr6cY1nootc69mJGQLPfk5izLcODF9hdQo__I,1676
+laco/integrations/logging/_core.py,sha256=EtbCaH9dZ9bViEPXHNyN8PHn-VQEAtX4Z9YqQZFaBec,2778
+laco/integrations/logging/mlflow.py,sha256=eJKBx55MfXWmpjmy51-PgPJIHiBFB06XEzrWspxv5z0,366
+laco/integrations/logging/tensorboard.py,sha256=PZXs3a3oNh-AMXOXDuQGfHYQWCZkQarqiER5v3O4JeQ,286
+laco/integrations/logging/wandb.py,sha256=Q1ihqBWpFvfXVKKnY0RYGCzzU4BvzgXbKmpZU8qEzA8,260
+laco/integrations/logging/_backends/__init__.py,sha256=iVb3zdnqAhRQPm4y5FVFaeR6Y5sBUIHeHb1lwYAJHaw,72
+laco/integrations/logging/_backends/mlflow.py,sha256=Z0tviDNGJmAMrEh5FOI5fPGn1q1sbgbZeQ8MaGJGIMA,1975
+laco/integrations/logging/_backends/tensorboard.py,sha256=CV-U7sYN1By3n3wGImk7pn5P54H3IbY9qZ7aV6Mk4uQ,2632
+laco/integrations/logging/_backends/wandb.py,sha256=LWUu0a7OJcIOoPTDTWZ_rWSY0cHA00k8YqbkarE7jPM,1284
+laco_logging-1.0.0.dist-info/METADATA,sha256=9QS-tC2bBVJ9duI-SxODlOqiCzQgGYEINYaqB4sg4Vc,1270
+laco_logging-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+laco_logging-1.0.0.dist-info/top_level.txt,sha256=G2kLu09Aje44OkSqu-Tae3mjmTYhyRc2VrTyh3OmxFw,5
+laco_logging-1.0.0.dist-info/RECORD,,

laco_logging-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_logging-1.0.0.dist-info/top_level.txt

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