euler-train 2.0.0__tar.gz → 2.2.0__tar.gz

{euler_train-2.0.0 → euler_train-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: euler-train
-Version: 2.0.0
+Version: 2.2.0
 Summary: Lightweight file-based experiment logger for PyTorch
 Requires-Python: >=3.9
 Requires-Dist: numpy

{euler_train-2.0.0 → euler_train-2.2.0}/README.md

@@ -80,9 +80,9 @@ The run ID and directory are available as `run.run_id` and `run.dir`.
 
 ## API reference
 
-### `euler_train.init(dir, config=None, meta=None, output_formats=None, run_id=None, datasets=None, run_name=None, evaluations=None, mode=None) → Run`
+### `euler_train.init(dir, config=None, meta=None, output_formats=None, output_visualization=None, run_id=None, datasets=None, run_name=None, evaluations=None, mode=None) → Run`
 
-Creates the run directory and writes `meta.json`, `config.json`, `code_ref.json`, and `run_environment.json`. On resume (`run_id` provided), only `meta.json` and `config.json` are updated.
+Creates the run directory and writes `meta.json`, `config.json`, `code_ref.json`, and `run_environment.json`. On resume (`run_id` provided), only `meta.json` and `config.json` are updated. `meta.json` also maintains an `updated_at` map with last-write timestamps for tracked artifacts.
 
 | Parameter | Type | Description |
 |---|---|---|
@@ -90,6 +90,7 @@ Creates the run directory and writes `meta.json`, `config.json`, `code_ref.json`
 | `config` | `dict \| str \| Path \| Namespace \| dataclass` | Hyperparameters. Paths to `.json` / `.yaml` files are loaded automatically. |
 | `meta` | `dict \| None` | Extra fields merged into `meta.json` (e.g. `{"tags": ["baseline"]}`). |
 | `output_formats` | `dict[str, str] \| None` | Override format inference (see [Format inference](#format-inference)). |
+| `output_visualization` | `dict[str, Any] \| None` | Override PNG visualization policy per output type / slot (see [Output visualization](#output-visualization)). |
 | `run_id` | `str \| None` | Resume an existing run at `{dir}/runs/{run_id}` instead of creating a new one. |
 | `datasets` | `dict[str, Any] \| None` | Optional split → dataset map. If a dataset exposes `describe_for_runlog()`, that contract is used directly; otherwise euler_train infers structured modality metadata (`path`, `used_as`, `slot`, `modality_type`, and hierarchical fields), resolving fixed namespaced properties from `properties.euler_loading` and `properties.euler_train` before heuristics. |
 | `run_name` | `str \| None` | Optional human-readable run label stored in `meta.json`. |
@@ -218,7 +219,7 @@ Arrays are saved as `.png` or `.npy` based on shape and dtype:
 |---|---|
 | `uint8` with shape `(H,W)` | `.png` (grayscale) |
 | Any dtype with shape `(H,W,1)`, `(H,W,3)`, `(H,W,4)` | `.png` |
-| Float `.png` | clipped to `[0,1]`, scaled to `[0,255]` |
+| Float `.png` | defaults to `unit_range`: clip to `[0,1]`, then scale to `[0,255]` |
 | Everything else (e.g. `float32 (H,W)`) | `.npy` |
 | PIL Image | `.png` |
 
@@ -240,6 +241,33 @@ run = euler_train.init(
 
 Supported formats: `"png"`, `"npy"`, `"npz"`.
 
+## Output visualization
+
+Float PNG outputs use a rendering policy before quantization to `uint8`. Policies are configured once at `init()` via `output_visualization`, and keys resolve most-specific-first just like `output_formats`:
+
+```python
+run = euler_train.init(
+    dir="runs/exp",
+    config=cfg,
+    output_visualization={
+        "depth": {"mode": "percentile", "pmin": 1, "pmax": 99},
+        "depth.pred": {"mode": "fixed_range", "vmin": 0.0, "vmax": 80.0},
+        "confidence": "minmax",
+    },
+)
+```
+
+Supported visualization modes:
+
+| Mode | Parameters | Description |
+|---|---|---|
+| `unit_range` | none | Clip float data to `[0,1]` before saving. |
+| `minmax` | none | Normalize using the finite-value min / max of the saved item. |
+| `percentile` | `pmin`, `pmax` | Normalize using finite-value percentiles, useful for depth-like outputs. |
+| `fixed_range` | `vmin`, `vmax` | Normalize against an explicit numeric range. |
+
+All float PNG policies also accept `invert: true` to flip black ↔ white after normalization.
+
 ## `meta.json` schema
 
 Auto-managed, not written to directly.
@@ -337,6 +365,24 @@ Auto-managed, not written to directly.
       "traceback": "Traceback (most recent call last):\n  ..."
     }
   },
+  "updated_at": {
+    "meta.json": {
+      "time": 1706403300.0,
+      "iso": "2025-01-28T16:25:00"
+    },
+    "config.json": {
+      "time": 1706400000.0,
+      "iso": "2025-01-28T15:30:42"
+    },
+    "train.jsonl": {
+      "time": 1706402999.0,
+      "iso": "2025-01-28T16:19:59"
+    },
+    "outputs/epoch_12_step_4800": {
+      "time": 1706403010.0,
+      "iso": "2025-01-28T16:20:10"
+    }
+  },
   "error": "RuntimeError: CUDA OOM",
   "traceback": "Traceback (most recent call last):\n  ..."
 }
@@ -347,6 +393,7 @@ Auto-managed, not written to directly.
 - `datasets` is only present when `datasets=...` is passed to `euler_train.init`.
 - `evaluations` is only present when evaluations are provided via `evaluations=...` on `init()` or added via `run.add_evaluation()`.
 - `modes` is only present when `mode=...` is passed to `euler_train.init`; each key stores the latest lifecycle snapshot for that mode.
+- `updated_at` stores last-write timestamps for tracked artifacts. Keys are run-relative paths when the artifact lives inside the run directory (for example `train.jsonl` or `outputs/epoch_2_step_500`) and absolute paths for external artifacts such as custom checkpoint locations.
 - `error` is only present when `status` is `"crashed"` (context manager / excepthook) or `"interrupted"` (SIGTERM/SIGINT). `traceback` is only present when `status` is `"crashed"`. When `mode=...` is set, the same fields are mirrored under `modes[mode]`.
 
 A formal JSON Schema for `meta.json` is available at [`meta-schema.json`](meta-schema.json).

{euler_train-2.0.0 → euler_train-2.2.0}/euler_train/__init__.py

@@ -1,6 +1,8 @@
 """runlog — lightweight file-based experiment logging."""
 from __future__ import annotations
 
+from typing import Any
+
 from . import _dataset_contract  # noqa: F401
 from .run import Run
 from .architecture import export_architecture
@@ -14,6 +16,7 @@ def init(
     config=None,
     meta: dict | None = None,
     output_formats: dict[str, str] | None = None,
+    output_visualization: dict[str, Any] | None = None,
     run_id: str | None = None,
     datasets: dict | None = None,
     run_name: str | None = None,
@@ -51,6 +54,11 @@ def init(
         (``"depth"``), a slot / aux name (``"transmission"``), or a
         dotted combination (``"depth.pred"``).  Values are ``"png"``,
         ``"npy"``, or ``"npz"``.
+    output_visualization:
+        Optional PNG rendering policy overrides. Keys resolve the same way
+        as *output_formats* (``"depth.pred"`` → ``"depth"`` → ``"pred"``).
+        Values can be a string mode (for example ``"percentile"``) or a
+        mapping such as ``{"mode": "fixed_range", "vmin": 0, "vmax": 80}``.
     run_id:
         If given, resume an existing run instead of creating a new one.
         The run directory ``{dir}/runs/{run_id}/`` must already exist.
@@ -84,7 +92,9 @@ def init(
     """
     return Run(
         dir=dir, config=config, meta=meta,
-        output_formats=output_formats, run_id=run_id,
+        output_formats=output_formats,
+        output_visualization=output_visualization,
+        run_id=run_id,
         datasets=datasets, run_name=run_name,
         evaluations=evaluations, mode=mode,
     )

{euler_train-2.0.0 → euler_train-2.2.0}/euler_train/outputs.py

@@ -1,6 +1,7 @@
 """Save prediction / ground-truth / auxiliary outputs to disk."""
 from __future__ import annotations
 
+from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
 
@@ -15,6 +16,7 @@ def save_output_tree(
     type_dir: Path,
     slots: dict[str, Any],
     format_overrides: dict[str, str],
+    visualization_overrides: dict[str, Any],
     output_type: str,
 ) -> None:
     """Persist all slots (pred, gt, input, aux/…) for one *output_type*.
@@ -35,13 +37,21 @@ def save_output_tree(
                 if aux_data is None:
                     continue
                 _save_slot(
-                    type_dir / "aux" / aux_name, aux_data,
-                    output_type, aux_name, format_overrides,
+                    type_dir / "aux" / aux_name,
+                    aux_data,
+                    output_type,
+                    aux_name,
+                    format_overrides,
+                    visualization_overrides,
                 )
         else:
             _save_slot(
-                type_dir / slot_name, data,
-                output_type, slot_name, format_overrides,
+                type_dir / slot_name,
+                data,
+                output_type,
+                slot_name,
+                format_overrides,
+                visualization_overrides,
             )
 
 
@@ -55,12 +65,16 @@ def _save_slot(
     output_type: str,
     leaf_name: str,
     format_overrides: dict[str, str],
+    visualization_overrides: dict[str, Any],
 ) -> None:
     slot_dir.mkdir(parents=True, exist_ok=True)
     items = _unpack(data)
+    visualization = _resolve_visualization(
+        output_type, leaf_name, visualization_overrides,
+    )
     for idx, item in enumerate(items):
         fmt = _resolve_format(item, output_type, leaf_name, format_overrides)
-        _save_item(slot_dir / f"{idx:04d}.{fmt}", item, fmt)
+        _save_item(slot_dir / f"{idx:04d}.{fmt}", item, fmt, visualization)
 
 
 # ---- normalisation -------------------------------------------------------
@@ -88,7 +102,12 @@ def _prepare(data: Any) -> Any:
 
     # torch Tensor → numpy, channels-first → channels-last
     if hasattr(data, "detach"):
-        arr: np.ndarray = data.detach().cpu().numpy()
+        tensor = data.detach().cpu()
+        try:
+            arr: np.ndarray = tensor.numpy()
+        except TypeError:
+            # NumPy cannot represent some torch dtypes (for example bfloat16).
+            arr = tensor.float().numpy()
         # (C, H, W) → (H, W, C)  when C looks like a channel dim
         if (
             arr.ndim == 3
@@ -119,14 +138,11 @@ def _is_image_like(arr: np.ndarray) -> bool:
     return False
 
 
-def _resolve_format(
-    item: Any,
+def _resolve_override(
     output_type: str,
     leaf_name: str,
-    overrides: dict[str, str],
-) -> str:
-    """Pick save format: check overrides (most-specific first), then infer."""
-    # "rgb.pred" > "rgb" > "pred"
+    overrides: Mapping[str, Any],
+) -> Any:
     specific = f"{output_type}.{leaf_name}"
     if specific in overrides:
         return overrides[specific]
@@ -134,6 +150,19 @@ def _resolve_format(
         return overrides[output_type]
     if leaf_name in overrides:
         return overrides[leaf_name]
+    return None
+
+
+def _resolve_format(
+    item: Any,
+    output_type: str,
+    leaf_name: str,
+    overrides: dict[str, str],
+) -> str:
+    """Pick save format: check overrides (most-specific first), then infer."""
+    override = _resolve_override(output_type, leaf_name, overrides)
+    if override is not None:
+        return str(override)
 
     # PIL Image
     try:
@@ -148,11 +177,34 @@ def _resolve_format(
     return "npy"
 
 
+def _resolve_visualization(
+    output_type: str,
+    leaf_name: str,
+    overrides: Mapping[str, Any],
+) -> dict[str, Any] | None:
+    override = _resolve_override(output_type, leaf_name, overrides)
+    if override is None:
+        return None
+    if isinstance(override, str):
+        return {"mode": override}
+    if isinstance(override, Mapping):
+        return dict(override)
+    raise TypeError(
+        "Visualization overrides must be strings or mappings, "
+        f"got {type(override)!r}",
+    )
+
+
 # ---- writers -------------------------------------------------------------
 
-def _save_item(path: Path, item: Any, fmt: str) -> None:
+def _save_item(
+    path: Path,
+    item: Any,
+    fmt: str,
+    visualization: dict[str, Any] | None = None,
+) -> None:
     if fmt == "png":
-        _save_png(path, item)
+        _save_png(path, item, visualization)
     elif fmt == "npy":
         np.save(str(path), item if isinstance(item, np.ndarray) else np.asarray(item))
     elif fmt == "npz":
@@ -164,7 +216,11 @@ def _save_item(path: Path, item: Any, fmt: str) -> None:
         raise ValueError(f"Unsupported format: {fmt!r}")
 
 
-def _save_png(path: Path, item: Any) -> None:
+def _save_png(
+    path: Path,
+    item: Any,
+    visualization: dict[str, Any] | None = None,
+) -> None:
     from PIL import Image
 
     # PIL Image — save directly
@@ -174,10 +230,9 @@ def _save_png(path: Path, item: Any) -> None:
 
     arr: np.ndarray = item
 
-    # float → [0,1] → uint8
+    # float → visualization policy → uint8
     if np.issubdtype(arr.dtype, np.floating):
-        arr = np.clip(arr, 0.0, 1.0)
-        arr = (arr * 255).astype(np.uint8)
+        arr = _render_float_png(arr, visualization)
     elif arr.dtype != np.uint8:
         arr = arr.astype(np.uint8)
 
@@ -192,3 +247,75 @@ def _save_png(path: Path, item: Any) -> None:
         Image.fromarray(plane, mode=mode).save(str(path))
     else:
         raise ValueError(f"Cannot save {arr.ndim}D array as PNG")
+
+
+def _render_float_png(
+    arr: np.ndarray,
+    visualization: dict[str, Any] | None,
+) -> np.ndarray:
+    policy = {"mode": "unit_range"}
+    if visualization is not None:
+        policy.update(visualization)
+
+    mode = str(policy.get("mode", "unit_range"))
+    finite = np.isfinite(arr)
+
+    if mode == "unit_range":
+        scaled = np.asarray(arr, dtype=np.float32)
+    elif mode == "minmax":
+        scaled = _normalize_minmax(arr, finite)
+    elif mode == "percentile":
+        pmin = float(policy.get("pmin", 1.0))
+        pmax = float(policy.get("pmax", 99.0))
+        if pmax <= pmin:
+            raise ValueError(
+                "Percentile visualization requires pmax > pmin, "
+                f"got pmin={pmin} pmax={pmax}",
+            )
+        scaled = _normalize_percentile(arr, finite, pmin, pmax)
+    elif mode == "fixed_range":
+        vmin = float(policy.get("vmin", 0.0))
+        vmax = float(policy.get("vmax", 1.0))
+        if vmax <= vmin:
+            raise ValueError(
+                "Fixed-range visualization requires vmax > vmin, "
+                f"got vmin={vmin} vmax={vmax}",
+            )
+        scaled = (np.asarray(arr, dtype=np.float32) - vmin) / (vmax - vmin)
+    else:
+        raise ValueError(f"Unsupported visualization mode: {mode!r}")
+
+    scaled = np.nan_to_num(scaled, nan=0.0, posinf=1.0, neginf=0.0)
+    if bool(policy.get("invert", False)):
+        scaled = 1.0 - scaled
+    scaled = np.clip(scaled, 0.0, 1.0)
+    return (scaled * 255).astype(np.uint8)
+
+
+def _normalize_minmax(arr: np.ndarray, finite: np.ndarray) -> np.ndarray:
+    values = arr[finite]
+    if values.size == 0:
+        return np.zeros_like(arr, dtype=np.float32)
+
+    vmin = float(values.min())
+    vmax = float(values.max())
+    if vmax <= vmin:
+        return np.zeros_like(arr, dtype=np.float32)
+    return (np.asarray(arr, dtype=np.float32) - vmin) / (vmax - vmin)
+
+
+def _normalize_percentile(
+    arr: np.ndarray,
+    finite: np.ndarray,
+    pmin: float,
+    pmax: float,
+) -> np.ndarray:
+    values = arr[finite]
+    if values.size == 0:
+        return np.zeros_like(arr, dtype=np.float32)
+
+    lo = float(np.percentile(values, pmin))
+    hi = float(np.percentile(values, pmax))
+    if hi <= lo:
+        return np.zeros_like(arr, dtype=np.float32)
+    return (np.asarray(arr, dtype=np.float32) - lo) / (hi - lo)

{euler_train-2.0.0 → euler_train-2.2.0}/euler_train/run.py

@@ -38,6 +38,7 @@ class Run:
         config: Any = None,
         meta: dict | None = None,
         output_formats: dict[str, str] | None = None,
+        output_visualization: dict[str, Any] | None = None,
         gpu_stats_every: int = 100,
         run_id: str | None = None,
         datasets: dict[str, Any] | None = None,
@@ -73,6 +74,7 @@ class Run:
 
         self.checkpoint_dir: Path | None = None
         self._output_formats: dict[str, str] = output_formats or {}
+        self._output_visualization: dict[str, Any] = output_visualization or {}
         self._start_time = time.time()
         self._finished = False
         self._gpu_handle: Any | None = None
@@ -80,6 +82,7 @@ class Run:
         self._gpu_stats_every: int = gpu_stats_every
         self.run_name: str | None = run_name
         self.mode: str | None = _normalize_mode(mode)
+        self._pending_updated_at: dict[str, dict[str, Any]] = {}
 
         # ── config ────────────────────────────────────────────────
         if resuming:
@@ -90,12 +93,19 @@ class Run:
         else:
             self.config: dict = normalize_config(config)
 
-        write_json(self.dir / "config.json", self.config)
+        config_path = self.dir / "config.json"
+        write_json(config_path, self.config)
+        self._record_artifact_update(config_path)
 
         # ── code ref & run environment (fresh runs only) ─────────
         if not resuming:
-            write_json(self.dir / "code_ref.json", get_code_ref())
-            write_json(self.dir / "run_environment.json", get_run_environment())
+            code_ref_path = self.dir / "code_ref.json"
+            write_json(code_ref_path, get_code_ref())
+            self._record_artifact_update(code_ref_path)
+
+            run_environment_path = self.dir / "run_environment.json"
+            write_json(run_environment_path, get_run_environment())
+            self._record_artifact_update(run_environment_path)
 
         # ── meta ──────────────────────────────────────────────────
         if resuming:
@@ -236,7 +246,10 @@ class Run:
             record.update(self._get_gpu_stats())
 
         filename = "train.jsonl" if mode == "train" else "val.jsonl"
-        append_jsonl(self.dir / filename, record)
+        log_path = self.dir / filename
+        append_jsonl(log_path, record)
+        self._record_artifact_update(log_path)
+        self._flush_meta()
 
     # ── GPU stats ─────────────────────────────────────────────────
 
@@ -305,8 +318,15 @@ class Run:
             if slots is None:
                 continue
             save_output_tree(
-                base / output_type, slots, self._output_formats, output_type,
+                base / output_type,
+                slots,
+                self._output_formats,
+                self._output_visualization,
+                output_type,
             )
+        if base.exists():
+            self._record_artifact_update(base)
+            self._flush_meta()
         return base
 
     # ── checkpoints ───────────────────────────────────────────────
@@ -333,6 +353,7 @@ class Run:
         if self.checkpoint_dir is not None:
             self.checkpoint_dir.mkdir(parents=True, exist_ok=True)
             self._meta["checkpoint_dir"] = str(self.checkpoint_dir)
+            self._record_artifact_update(self.checkpoint_dir)
             self._flush_meta()
             log.info("Checkpoint dir: %s", self.checkpoint_dir)
             return self.checkpoint_dir
@@ -351,6 +372,7 @@ class Run:
             )
         self.checkpoint_dir.mkdir(parents=True, exist_ok=True)
         self._meta["checkpoint_dir"] = str(self.checkpoint_dir)
+        self._record_artifact_update(self.checkpoint_dir)
         self._flush_meta()
         log.info("Checkpoint dir: %s", self.checkpoint_dir)
         return self.checkpoint_dir
@@ -409,6 +431,7 @@ class Run:
         :meth:`save_checkpoint` call it automatically.  When *is_best*
         is ``True``, any previous checkpoint marked as best is cleared.
         """
+        checkpoint_path = Path(path)
         checkpoints: list[dict[str, Any]] = self._meta.get("checkpoints", [])
 
         if is_best:
@@ -416,7 +439,7 @@ class Run:
                 entry.pop("is_best", None)
 
         record: dict[str, Any] = {
-            "path": str(path),
+            "path": str(checkpoint_path),
             "epoch": epoch,
             "step": step,
         }
@@ -425,6 +448,7 @@ class Run:
 
         checkpoints.append(record)
         self._meta["checkpoints"] = checkpoints
+        self._record_artifact_update(checkpoint_path)
         self._flush_meta()
 
     # ── architecture export ─────────────────────────────────────────
@@ -461,6 +485,7 @@ class Run:
             model, dummy_input, self.dir / "architecture.onnx"
         )
         self._meta["architecture"] = "architecture.onnx"
+        self._record_artifact_update(output_path)
         self._flush_meta()
         return output_path
 
@@ -646,7 +671,45 @@ class Run:
         self._meta["modes"] = modes
         return modes
 
+    def _updated_at_store(self) -> dict[str, Any]:
+        if not hasattr(self, "_meta"):
+            return self._pending_updated_at
+
+        updated_at = self._meta.get("updated_at")
+        if not isinstance(updated_at, dict):
+            updated_at = {}
+            self._meta["updated_at"] = updated_at
+
+        if self._pending_updated_at:
+            updated_at.update(self._pending_updated_at)
+            self._pending_updated_at.clear()
+
+        return updated_at
+
+    def _record_artifact_update(
+        self,
+        path: str | Path,
+        *,
+        when: float | None = None,
+    ) -> None:
+        artifact_path = Path(path)
+        ts = when if when is not None else _artifact_mtime(artifact_path)
+        if ts is None:
+            ts = time.time()
+        self._updated_at_store()[self._artifact_key(artifact_path)] = (
+            _updated_at_entry(ts)
+        )
+
+    def _artifact_key(self, path: Path) -> str:
+        if path.is_absolute():
+            try:
+                return path.relative_to(self.dir).as_posix()
+            except ValueError:
+                return str(path)
+        return path.as_posix()
+
     def _flush_meta(self) -> None:
+        self._record_artifact_update(self.dir / "meta.json", when=time.time())
         write_json(self.dir / "meta.json", self._meta)
 
     def __repr__(self) -> str:
@@ -726,6 +789,20 @@ def _isotime(ts: float) -> str:
     return time.strftime("%Y-%m-%dT%H:%M:%S", time.localtime(ts))
 
 
+def _updated_at_entry(ts: float) -> dict[str, Any]:
+    return {
+        "time": ts,
+        "iso": _isotime(ts),
+    }
+
+
+def _artifact_mtime(path: Path) -> float | None:
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return None
+
+
 def _normalize_mode(mode: str | None) -> str | None:
     if mode is None:
         return None
@@ -1044,6 +1121,9 @@ def _read_ds_crawler_descriptor(path: str) -> dict[str, Any]:
     try:
         cfg = load_dataset_config({"path": path})
     except Exception:
+        descriptor = _read_output_json_descriptor(path)
+        if descriptor:
+            return descriptor
         try:
             contract = get_dataset_contract(path)
         except Exception:
@@ -1076,6 +1156,69 @@ def _read_ds_crawler_descriptor(path: str) -> dict[str, Any]:
     return descriptor
 
 
+def _read_output_json_descriptor(path: str) -> dict[str, Any]:
+    try:
+        from ds_crawler import zip_utils
+    except Exception:
+        return {}
+
+    try:
+        raw = zip_utils.read_metadata_json(Path(path), "output.json")
+    except Exception:
+        return {}
+
+    return _descriptor_from_output_json(raw, path)
+
+
+def _descriptor_from_output_json(raw: Any, path: str) -> dict[str, Any]:
+    if isinstance(raw, Mapping):
+        candidates: list[Any]
+        modalities = raw.get("modalities")
+        if isinstance(modalities, list):
+            candidates = modalities
+        else:
+            candidates = [raw]
+    elif isinstance(raw, list):
+        candidates = raw
+    else:
+        return {}
+
+    selected: Mapping[str, Any] | None = None
+    path_name = Path(path).name
+    for candidate in candidates:
+        if not isinstance(candidate, Mapping):
+            continue
+        if _as_non_empty_str(candidate.get("name")) == path_name:
+            selected = candidate
+            break
+        if selected is None:
+            selected = candidate
+
+    if selected is None:
+        return {}
+
+    descriptor: dict[str, Any] = {}
+    properties = selected.get("properties")
+    merged_properties = dict(properties) if isinstance(properties, Mapping) else {}
+
+    euler_train_props = selected.get("euler_train")
+    if isinstance(euler_train_props, Mapping):
+        merged_properties["euler_train"] = dict(euler_train_props)
+
+    if merged_properties:
+        descriptor["properties"] = merged_properties
+
+    modality_key = _as_non_empty_str(selected.get("type"))
+    if modality_key is not None:
+        descriptor["modality_key"] = modality_key
+
+    hierarchy_regex = _as_non_empty_str(selected.get("hierarchy_regex"))
+    if hierarchy_regex is not None:
+        descriptor["hierarchy_regex"] = hierarchy_regex
+
+    return descriptor
+
+
 def _build_modality_entry(
     name: str,
     path: str,

{euler_train-2.0.0 → euler_train-2.2.0}/euler_train.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: euler-train
-Version: 2.0.0
+Version: 2.2.0
 Summary: Lightweight file-based experiment logger for PyTorch
 Requires-Python: >=3.9
 Requires-Dist: numpy

{euler_train-2.0.0 → euler_train-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "euler-train"
-version = "2.0.0"
+version = "2.2.0"
 description = "Lightweight file-based experiment logger for PyTorch"
 requires-python = ">=3.9"
 dependencies = ["numpy", "euler-dataset-contract"]

{euler_train-2.0.0 → euler_train-2.2.0}/tests/test_runlog.py

@@ -27,6 +27,12 @@ def _read_jsonl(path: Path) -> list[dict]:
     return [json.loads(line) for line in path.read_text().splitlines() if line.strip()]
 
 
+def _assert_updated_at_entry(entry: dict) -> None:
+    assert isinstance(entry["time"], (int, float))
+    assert isinstance(entry["iso"], str)
+    assert entry["iso"]
+
+
 class _DummyModality:
     def __init__(self, path: str) -> None:
         self.path = path
@@ -228,6 +234,57 @@ class TestInit:
         run.finish()
 
 
+class TestUpdatedAt:
+    def test_init_tracks_bootstrap_artifacts(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+
+        meta = _read_json(run.dir / "meta.json")
+        updated_at = meta["updated_at"]
+
+        for key in (
+            "meta.json",
+            "config.json",
+            "code_ref.json",
+            "run_environment.json",
+        ):
+            assert key in updated_at
+            _assert_updated_at_entry(updated_at[key])
+        run.finish()
+
+    def test_log_tracks_train_and_val_jsonl(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+
+        run.log({"loss": 1.0}, step=0, epoch=0)
+        run.log({"metric": 0.9}, step=1, epoch=0, mode="val")
+
+        meta = _read_json(run.dir / "meta.json")
+        updated_at = meta["updated_at"]
+        _assert_updated_at_entry(updated_at["train.jsonl"])
+        _assert_updated_at_entry(updated_at["val.jsonl"])
+        _assert_updated_at_entry(updated_at["meta.json"])
+        run.finish()
+
+    def test_save_outputs_tracks_output_directory(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+        arr = np.zeros((4, 4, 3), dtype=np.uint8)
+
+        run.save_outputs(epoch=0, step=0, rgb=dict(pred=arr))
+
+        meta = _read_json(run.dir / "meta.json")
+        _assert_updated_at_entry(meta["updated_at"]["outputs/epoch_0_step_0"])
+        run.finish()
+
+    def test_log_saved_checkpoint_tracks_checkpoint_path(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+        checkpoint_path = tmp_path / "external" / "epoch_1.pt"
+
+        run.log_saved_checkpoint(checkpoint_path, epoch=1, step=10)
+
+        meta = _read_json(run.dir / "meta.json")
+        _assert_updated_at_entry(meta["updated_at"][str(checkpoint_path)])
+        run.finish()
+
+
 class TestDatasetMetadata:
     def test_prefers_dataset_describe_for_runlog_contract(
         self, tmp_path, monkeypatch
@@ -1168,6 +1225,61 @@ class TestSaveOutputsOverrides:
         run.finish()
 
 
+class TestSaveOutputsVisualization:
+    def test_fixed_range_visualization_for_single_channel_png(self, tmp_path):
+        run = euler_train.init(
+            dir=str(tmp_path / "r"),
+            config={},
+            output_visualization={
+                "depth": {"mode": "fixed_range", "vmin": 0.0, "vmax": 10.0},
+            },
+        )
+        depth = np.linspace(0.0, 10.0, 16, dtype=np.float32).reshape(4, 4, 1)
+        run.save_outputs(epoch=0, step=0, depth=dict(pred=depth))
+
+        f = list((run.dir / "outputs" / "epoch_0_step_0" / "depth" / "pred").iterdir())[0]
+        img = np.array(Image.open(f))
+        assert f.suffix == ".png"
+        assert img.min() == 0
+        assert img.max() == 255
+        run.finish()
+
+    def test_visualization_override_specific_dotted_key(self, tmp_path):
+        run = euler_train.init(
+            dir=str(tmp_path / "r"),
+            config={},
+            output_visualization={
+                "depth.pred": {"mode": "fixed_range", "vmin": 5.0, "vmax": 15.0},
+            },
+        )
+        depth = np.linspace(5.0, 15.0, 16, dtype=np.float32).reshape(4, 4, 1)
+        run.save_outputs(epoch=0, step=0, depth=dict(pred=depth, gt=depth))
+
+        base = run.dir / "outputs" / "epoch_0_step_0" / "depth"
+        pred_f = list((base / "pred").iterdir())[0]
+        gt_f = list((base / "gt").iterdir())[0]
+        pred_img = np.array(Image.open(pred_f))
+        gt_img = np.array(Image.open(gt_f))
+        assert pred_img.min() == 0
+        assert pred_img.max() == 255
+        assert gt_img.min() == 255
+        assert gt_img.max() == 255
+        run.finish()
+
+    def test_torch_bfloat16_single_channel_png_promoted_to_float32(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+        t = torch.linspace(0, 1, steps=16, dtype=torch.bfloat16).reshape(4, 4, 1)
+        run.save_outputs(epoch=0, step=0, confidence=dict(pred=t))
+
+        f = list((run.dir / "outputs" / "epoch_0_step_0" / "confidence" / "pred").iterdir())[0]
+        img = np.array(Image.open(f))
+        assert f.suffix == ".png"
+        assert img.dtype == np.uint8
+        assert img.min() == 0
+        assert img.max() >= 254
+        run.finish()
+
+
 # ═══════════════════════════════════════════════════════════════════════════
 #  save_outputs  — batches, lists, aux, PIL, torch
 # ═══════════════════════════════════════════════════════════════════════════