laco-logging 1.0.0__tar.gz

laco_logging-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,28 @@
+# 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/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=75", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "laco-logging"
+version = "1.0.0"
+description = "Unified experiment logging (W&B, MLflow, TensorBoard) for laco."
+readme = "README.md"
+requires-python = ">=3.13"
+authors = [{ name = "Kurt Stolle", email = "kurt@khws.io" }]
+dependencies = ["laco>=1.0.0"]
+
+[project.optional-dependencies]
+wandb = ["wandb>=0.19"]
+mlflow = ["mlflow>=2.0"]
+tensorboard = ["tensorboard>=2.0"]
+all = ["wandb>=0.19", "mlflow>=2.0", "tensorboard>=2.0"]
+
+[tool.setuptools.packages.find]
+where = ["sources"]
+namespaces = true
+
+[tool.uv.sources]
+laco = { workspace = true }

laco_logging-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

laco_logging-1.0.0/sources/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_logging-1.0.0/sources/laco/integrations/logging/_backends/__init__.py

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

laco_logging-1.0.0/sources/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_logging-1.0.0/sources/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_logging-1.0.0/sources/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_logging-1.0.0/sources/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_logging-1.0.0/sources/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_logging-1.0.0/sources/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_logging-1.0.0/sources/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/sources/laco_logging.egg-info/PKG-INFO

@@ -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/sources/laco_logging.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+sources/laco/integrations/logging/__init__.py
+sources/laco/integrations/logging/_core.py
+sources/laco/integrations/logging/mlflow.py
+sources/laco/integrations/logging/tensorboard.py
+sources/laco/integrations/logging/wandb.py
+sources/laco/integrations/logging/_backends/__init__.py
+sources/laco/integrations/logging/_backends/mlflow.py
+sources/laco/integrations/logging/_backends/tensorboard.py
+sources/laco/integrations/logging/_backends/wandb.py
+sources/laco_logging.egg-info/PKG-INFO
+sources/laco_logging.egg-info/SOURCES.txt
+sources/laco_logging.egg-info/dependency_links.txt
+sources/laco_logging.egg-info/requires.txt
+sources/laco_logging.egg-info/top_level.txt
+tests/test_laco_logging.py

laco_logging-1.0.0/sources/laco_logging.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

laco_logging-1.0.0/sources/laco_logging.egg-info/requires.txt

@@ -0,0 +1,15 @@
+laco>=1.0.0
+
+[all]
+wandb>=0.19
+mlflow>=2.0
+tensorboard>=2.0
+
+[mlflow]
+mlflow>=2.0
+
+[tensorboard]
+tensorboard>=2.0
+
+[wandb]
+wandb>=0.19

laco_logging-1.0.0/sources/laco_logging.egg-info/top_level.txt

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

laco_logging-1.0.0/tests/test_laco_logging.py

@@ -0,0 +1,50 @@
+"""Tests for laco-logging."""
+
+import pytest
+
+
+def test_import():
+    import laco.integrations.logging  # noqa: F401
+
+
+def test_public_api():
+    import laco.integrations.logging as laco_logging
+
+    assert hasattr(laco_logging, "log_config")
+    assert hasattr(laco_logging, "run")
+    assert "log_config" in laco_logging.__all__
+    assert "run" in laco_logging.__all__
+
+
+def test_log_config_unknown_backend_raises():
+    import laco.integrations.logging as laco_logging
+    from omegaconf import OmegaConf
+
+    cfg = OmegaConf.create({"lr": 0.001})
+    with pytest.raises(ValueError, match="Unknown backend"):
+        laco_logging.log_config(cfg, "nonexistent_backend")
+
+
+def test_run_unknown_backend_raises():
+    import laco.integrations.logging as laco_logging
+    from omegaconf import OmegaConf
+
+    cfg = OmegaConf.create({"lr": 0.001})
+    with pytest.raises(ValueError, match="Unknown backend"):
+        with laco_logging.run(cfg, backend="nonexistent_backend"):
+            pass
+
+
+def test_log_config_list_of_backends_invalid_raises():
+    import laco.integrations.logging as laco_logging
+    from omegaconf import OmegaConf
+
+    cfg = OmegaConf.create({})
+    with pytest.raises(ValueError, match="Unknown backend"):
+        laco_logging.log_config(cfg, ["wandb", "invalid"])
+
+
+def test_backend_submodules_importable():
+    import laco.integrations.logging.mlflow  # noqa: F401
+    import laco.integrations.logging.tensorboard  # noqa: F401
+    import laco.integrations.logging.wandb  # noqa: F401