euler-train 2.5.0__tar.gz → 2.7.0__tar.gz

{euler_train-2.5.0 → euler_train-2.7.0}/PKG-INFO

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

{euler_train-2.5.0 → euler_train-2.7.0}/README.md

@@ -49,6 +49,57 @@ with euler_train.init(dir="runs/exp02", config=cfg) as run:
     ...  # if an exception is raised, meta.json records status="crashed" + traceback
 ```
 
+## Euler View stream mode
+
+`euler_train` can dual-write runs to Euler View while still keeping the normal file-based run directory as the primary source of truth. Streaming is best-effort: local files are always written first, and stream events are sent alongside them when a stream consumer is configured.
+
+Pass the stream config via `stream=...` on `euler_train.init()`:
+
+```python
+import os
+import euler_train
+
+run = euler_train.init(
+    dir="runs/experiment_01",
+    config=cfg,
+    stream={
+        "base_url": os.environ["EULER_VIEW_BASE_URL"],
+        "model_id": 42,
+        "api_token": os.environ["EULER_VIEW_API_TOKEN"],
+        "stream_attach_token": os.environ.get("EULER_VIEW_STREAM_ATTACH_TOKEN"),
+    },
+)
+```
+
+What each field is for:
+
+- `base_url`: Euler View server base URL, for example `https://view.example.com`.
+- `model_id`: Euler View model that should receive this run.
+- `api_token` or `access_token`: credential used to open a stream session. This is the normal choice when the package should negotiate its own short-lived ingest token.
+- `stream_attach_token`: optional opaque launch-attachment token. When present, the producer sends it during the session handshake and Euler View attaches the stream to that launch directly. This is the preferred path for interactive or otherwise non-SLURM launches. Internally Euler View currently maps this token to `model_launches.id`, but the package treats it as an opaque token.
+- `stream_token`: optional pre-issued ingest token. If you pass this, the package skips the session handshake entirely and posts events directly to the ingest endpoint.
+- `datasource_id`: optional Euler View datasource hint for the run record.
+- `euler_train_dir` and `run_dir`: optional path overrides. These are auto-derived in normal usage.
+- `session_expires_in_sec`: optional requested session lifetime for the short-lived ingest token.
+
+How the handshake works:
+
+1. `euler_train` creates the local run directory and writes `meta.json`, `config.json`, and the other standard files as usual.
+2. When the first stream flush happens, the package requests a session from Euler View at `/api/models/{model_id}/runs/{run_id}/stream/session`.
+3. If `stream_attach_token` is configured, it is sent as `streamAttachToken` and used as the explicit launch attachment key.
+4. If no `stream_attach_token` is configured, the package falls back to the SLURM metadata already captured in `meta.json["slurm"]["job_id"]`.
+5. Euler View returns a short-lived ingest token plus the canonical `streamAttachToken`; the package caches that returned token and reuses it on later session refreshes.
+6. Subsequent events are sent to `/api/model-run-stream/ingest`.
+
+What has to be configured where:
+
+- In the training script or job wrapper: pass `stream={...}` to `euler_train.init(...)`.
+- In Euler View / the launcher: if the run should attach to a specific launch regardless of SLURM availability, provide a `stream_attach_token` to the runtime and forward it into the `stream` config.
+- Under plain SLURM launches: no extra attachment config is required as long as Euler View can uniquely match the run by `slurm.job_id`.
+- If neither `stream_attach_token` nor a unique SLURM match is available, run streaming still works, but launch-to-run linking in Euler View may remain unresolved.
+
+For new integrations, prefer `stream_attach_token`. The older `launch_id` / `launchId` config keys are still accepted as compatibility aliases, but new code should treat the attachment value as an opaque stream token rather than a launch ID.
+
 ## Directory structure
 
 Each `euler_train.init(dir=...)` call creates a timestamped subdirectory under `{dir}/runs/`:
@@ -67,6 +118,7 @@ Each `euler_train.init(dir=...)` call creates a timestamped subdirectory under `
         │   └── epoch_{N}.pt
         └── outputs/
             └── epoch_{N}_step_{M}/
+                ├── manifest.json
                 └── {output_type}/
                     ├── pred/
                     ├── gt/
@@ -80,7 +132,7 @@ 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, output_visualization=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, stream=None, metric_naming=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. `meta.json` also maintains an `updated_at` map with last-write timestamps for tracked artifacts.
 
@@ -96,6 +148,8 @@ Creates the run directory and writes `meta.json`, `config.json`, `code_ref.json`
 | `run_name` | `str \| None` | Optional human-readable run label stored in `meta.json`. |
 | `evaluations` | `dict[str, dict] \| None` | Optional evaluation key → entry map. See [Evaluations](#evaluations). |
 | `mode` | `str \| None` | Optional process label such as `"train"`, `"val"`, or `"eval"`. When set, lifecycle and crash details are also written under `meta.json["modes"][mode]`. |
+| `stream` | `dict \| EulerViewStreamConfig \| consumer \| sequence \| None` | Optional output stream config / consumer. A mapping with `base_url`, `model_id`, and `api_token` (or `access_token`) enables best-effort streaming to Euler View. Prefer `stream_attach_token` for explicit launch attachment; otherwise the package falls back to `meta.json["slurm"]["job_id"]` when available. |
+| `metric_naming` | `dict[str, Any] \| None` | Optional structured metric naming declaration stored in `meta.json["metric_naming"]` and included in the stream init event. |
 
 ---
 
@@ -112,7 +166,7 @@ run.log({"rgb.psnr": 28.3, "depth.mae": 0.03}, step=100, epoch=1, mode="val")
 
 ---
 
-### `run.save_outputs(*, epoch=None, step=None, **output_types)`
+### `run.save_outputs(*, epoch=None, step=None, metadata=None, **output_types)`
 
 Saves arrays/images to `outputs/epoch_{N}_step_{M}/{output_type}/{slot}/`.
 
@@ -125,10 +179,11 @@ Each output type is a dict with these slot keys:
 | `input` | Model input |
 | `aux` | Dict of named auxiliary outputs (each becomes a subdirectory) |
 
-Values can be:
+Slot values can be:
 - A single numpy array, torch tensor, or PIL Image
 - A list of the above (saved as `0000.ext`, `0001.ext`, ...)
 - A 4D numpy/torch array (split along dim 0 as a batch)
+- A dict mapping custom string IDs to items (saved as `{id}.ext`)
 
 ```python
 run.save_outputs(
@@ -142,6 +197,61 @@ run.save_outputs(
 )
 ```
 
+#### Named sample IDs
+
+When slot values are dicts with string keys, files are saved with the key as the basename instead of sequential indices. This is useful for matching outputs back to specific input samples:
+
+```python
+run.save_outputs(
+    epoch=1, step=500,
+    rgb=dict(pred={"scene_042": img_a, "scene_117": img_b}),
+)
+# produces: rgb/pred/scene_042.png, rgb/pred/scene_117.png
+```
+
+#### Source metadata
+
+The optional `metadata` parameter attaches dataset provenance and other context to the output manifest. When provided, the `dataset` key is required and must be a non-empty string:
+
+```python
+run.save_outputs(
+    epoch=1, step=500,
+    metadata={"dataset": "vkitti2", "split": "val", "scene": "0001"},
+    rgb=dict(pred={"frame_042": img_a}),
+)
+```
+
+#### Output manifest
+
+Each `save_outputs` call writes a `manifest.json` alongside the saved files, recording what was written and how. The manifest is also streamed via the `output_snapshot` event when streaming is active.
+
+```json
+{
+  "version": 1,
+  "epoch": 1,
+  "step": 500,
+  "metadata": {"dataset": "vkitti2", "split": "val"},
+  "output_types": {
+    "rgb": {
+      "pred": {
+        "id_mode": "named",
+        "files": [
+          {"sample_id": "scene_042", "filename": "scene_042.png", "format": "png"}
+        ]
+      },
+      "gt": {
+        "id_mode": "indexed",
+        "files": [
+          {"sample_id": 0, "filename": "0000.png", "format": "png"}
+        ]
+      }
+    }
+  },
+  "format_overrides": {},
+  "visualization_overrides": {}
+}
+```
+
 Torch tensors in `(C,H,W)` or `(B,C,H,W)` layout are automatically transposed to channels-last before saving.
 
 Pass `None` for any slot or output type to skip it.

{euler_train-2.5.0 → euler_train-2.7.0}/euler_train/outputs.py

@@ -18,7 +18,7 @@ def save_output_tree(
     format_overrides: dict[str, str],
     visualization_overrides: dict[str, Any],
     output_type: str,
-) -> None:
+) -> dict[str, Any]:
     """Persist all slots (pred, gt, input, aux/…) for one *output_type*.
 
     *slots* example::
@@ -28,7 +28,10 @@ def save_output_tree(
             "gt":   array,
             "aux":  {"transmission": array, "attention": array},
         }
+
+    Returns a dict mapping slot keys to their manifest entries.
     """
+    manifest: dict[str, Any] = {}
     for slot_name, data in slots.items():
         if data is None:
             continue
@@ -36,7 +39,7 @@ def save_output_tree(
             for aux_name, aux_data in data.items():
                 if aux_data is None:
                     continue
-                _save_slot(
+                manifest[f"aux/{aux_name}"] = _save_slot(
                     type_dir / "aux" / aux_name,
                     aux_data,
                     output_type,
@@ -45,7 +48,7 @@ def save_output_tree(
                     visualization_overrides,
                 )
         else:
-            _save_slot(
+            manifest[slot_name] = _save_slot(
                 type_dir / slot_name,
                 data,
                 output_type,
@@ -53,6 +56,7 @@ def save_output_tree(
                 format_overrides,
                 visualization_overrides,
             )
+    return manifest
 
 
 # ---------------------------------------------------------------------------
@@ -66,7 +70,8 @@ def _save_slot(
     leaf_name: str,
     format_overrides: dict[str, str],
     visualization_overrides: dict[str, Any],
-) -> None:
+) -> dict[str, Any]:
+    """Save items for one slot and return a manifest entry."""
     slot_dir.mkdir(parents=True, exist_ok=True)
     visualization = _resolve_visualization(
         output_type, leaf_name, visualization_overrides,
@@ -74,16 +79,21 @@ def _save_slot(
 
     # Dict with string keys → named outputs (e.g. {"scene_042": img}).
     if isinstance(data, dict):
+        files: list[dict[str, Any]] = []
         for name, raw in data.items():
             item = _prepare(raw)
             fmt = _resolve_format(item, output_type, leaf_name, format_overrides)
             _save_item(slot_dir / f"{name}.{fmt}", item, fmt, visualization)
-        return
+            files.append({"sample_id": name, "filename": f"{name}.{fmt}", "format": fmt})
+        return {"id_mode": "named", "files": files}
 
     items = _unpack(data)
+    files = []
     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, visualization)
+        files.append({"sample_id": idx, "filename": f"{idx:04d}.{fmt}", "format": fmt})
+    return {"id_mode": "indexed", "files": files}
 
 
 # ---- normalisation -------------------------------------------------------

{euler_train-2.5.0 → euler_train-2.7.0}/euler_train/run.py

@@ -361,6 +361,7 @@ class Run:
         *,
         epoch: int | None = None,
         step: int | None = None,
+        metadata: dict[str, Any] | None = None,
         **output_types: dict[str, Any],
     ) -> Path:
         """Save prediction / ground-truth / auxiliary arrays to disk.
@@ -383,11 +384,26 @@ class Run:
                 rgb=dict(pred={"scene_042": img_a, "scene_117": img_b}),
             )
 
+        An optional *metadata* dict attaches source context (dataset,
+        split, etc.) to the manifest.  The ``dataset`` key is required
+        when *metadata* is provided::
+
+            run.save_outputs(
+                epoch=1, step=500,
+                metadata={"dataset": "vkitti2", "split": "val"},
+                rgb=dict(pred=pred_img),
+            )
+
         Accepted slot keys: ``pred``, ``gt``, ``input``, ``aux``.
         ``aux`` expects a sub-dict of named arrays.
 
         Returns the directory that was written to.
         """
+        if metadata is not None:
+            if not isinstance(metadata.get("dataset"), str) or not metadata["dataset"].strip():
+                raise ValueError(
+                    "metadata must include a non-empty 'dataset' string"
+                )
         parts: list[str] = []
         if epoch is not None:
             parts.append(f"epoch_{epoch}")
@@ -396,21 +412,38 @@ class Run:
         dirname = "_".join(parts) or "unspecified"
         base = self.dir / "outputs" / dirname
 
+        manifest_types: dict[str, Any] = {}
         for output_type, slots in output_types.items():
             if slots is None:
                 continue
-            save_output_tree(
+            slot_manifest = save_output_tree(
                 base / output_type,
                 slots,
                 self._output_formats,
                 self._output_visualization,
                 output_type,
             )
+            if slot_manifest:
+                manifest_types[output_type] = slot_manifest
+        if manifest_types:
+            manifest: dict[str, Any] = {
+                "version": 1,
+                "epoch": epoch,
+                "step": step,
+                "output_types": manifest_types,
+                "format_overrides": dict(self._output_formats),
+                "visualization_overrides": {
+                    k: dict(v) if isinstance(v, Mapping) else v
+                    for k, v in self._output_visualization.items()
+                } if self._output_visualization else {},
+            }
+            if metadata is not None:
+                manifest["metadata"] = metadata
+            write_json(base / "manifest.json", manifest)
         if base.exists():
             self._record_artifact_update(base)
             self._flush_meta()
-            snapshot = self._build_output_snapshot(epoch, step, output_types)
-            if snapshot is not None:
+            if manifest_types and epoch is not None and step is not None:
                 self._emit_stream_event(
                     {
                         "type": "output_snapshot",
@@ -419,7 +452,13 @@ class Run:
                             epoch,
                             step,
                         ),
-                        "snapshot": snapshot,
+                        "snapshot": {
+                            "version": 1,
+                            "epoch": epoch,
+                            "step": step,
+                            "output_types": manifest_types,
+                            **({"metadata": metadata} if metadata is not None else {}),
+                        },
                     },
                 )
         return base
@@ -888,44 +927,6 @@ class Run:
         ]
         return tags or None
 
-    def _build_output_snapshot(
-        self,
-        epoch: int | None,
-        step: int | None,
-        output_types: dict[str, Any],
-    ) -> dict[str, Any] | None:
-        if epoch is None or step is None:
-            return None
-
-        snapshot_types: dict[str, list[str]] = {}
-        for output_type, slots in output_types.items():
-            if slots is None or not isinstance(slots, Mapping):
-                continue
-
-            categories: list[str] = []
-            for slot_name, data in slots.items():
-                if data is None:
-                    continue
-                if slot_name == "aux" and isinstance(data, Mapping):
-                    for aux_name, aux_value in data.items():
-                        if aux_value is None:
-                            continue
-                        categories.append(f"aux/{aux_name}")
-                else:
-                    categories.append(str(slot_name))
-
-            if categories:
-                snapshot_types[str(output_type)] = sorted(set(categories))
-
-        if not snapshot_types:
-            return None
-
-        return {
-            "epoch": epoch,
-            "step": step,
-            "types": snapshot_types,
-        }
-
     def _build_finish_patch(self) -> dict[str, Any]:
         patch = {
             "end_time": self._meta.get("end_time"),

{euler_train-2.5.0 → euler_train-2.7.0}/euler_train/stream.py

@@ -56,6 +56,8 @@ class EulerViewStreamConfig:
     api_token: str | None = None
     access_token: str | None = None
     stream_token: str | None = None
+    stream_attach_token: str | None = None
+    launch_id: str | None = None
     datasource_id: int | None = None
     euler_train_dir: str | None = None
     run_dir: str | None = None
@@ -84,6 +86,24 @@ class EulerViewStreamConfig:
             self.stream_token,
             field_name="stream.stream_token",
         )
+        self.stream_attach_token = _normalize_optional_text(
+            self.stream_attach_token,
+            field_name="stream.stream_attach_token",
+        )
+        self.launch_id = _normalize_optional_text(
+            self.launch_id,
+            field_name="stream.launch_id",
+        )
+        if (
+            self.stream_attach_token is not None
+            and self.launch_id is not None
+            and self.stream_attach_token != self.launch_id
+        ):
+            raise ValueError(
+                "stream.stream_attach_token and stream.launch_id must match when both are provided",
+            )
+        if self.stream_attach_token is None:
+            self.stream_attach_token = self.launch_id
         self.euler_train_dir = _normalize_optional_text(
             self.euler_train_dir,
             field_name="stream.euler_train_dir",
@@ -191,6 +211,7 @@ class EulerViewStreamConsumer:
         self._context: StreamContext | None = None
         self._pending: list[dict[str, Any]] = []
         self._stream_token: str | None = config.stream_token
+        self._resolved_stream_attach_token: str | None = config.stream_attach_token
         self._session_expires_at = float("inf") if config.stream_token else 0.0
         self._ingest_url = f"{self.config.base_url}/api/model-run-stream/ingest"
         self._last_flush_at = 0.0
@@ -299,6 +320,14 @@ class EulerViewStreamConsumer:
             "runDir": self.config.run_dir or str(self._context.run_dir),
             "eulerTrainDir": self.config.euler_train_dir or str(self._context.runs_dir),
         }
+        stream_attach_token = (
+            self.config.stream_attach_token or self._resolved_stream_attach_token
+        )
+        if stream_attach_token is not None:
+            session_body["streamAttachToken"] = stream_attach_token
+        slurm_job_id = _extract_slurm_job_id(self._context.meta)
+        if slurm_job_id is not None:
+            session_body["slurmJobId"] = slurm_job_id
         if self.config.datasource_id is not None:
             session_body["datasourceId"] = self.config.datasource_id
         if self.config.session_expires_in_sec is not None:
@@ -328,6 +357,10 @@ class EulerViewStreamConsumer:
         else:
             self._ingest_url = f"{self.config.base_url}/api/model-run-stream/ingest"
 
+        resolved_stream_attach_token = _extract_session_stream_attach_token(payload)
+        if resolved_stream_attach_token is not None:
+            self._resolved_stream_attach_token = resolved_stream_attach_token
+
         self._session_expires_at = _parse_timestamp(payload.get("expiresAt"))
         self._next_retry_at = 0.0
         return True
@@ -448,6 +481,12 @@ def _config_from_mapping(raw: Mapping[str, Any]) -> EulerViewStreamConfig:
         access_token=_mapping_get(raw, "access_token", "accessToken"),
         api_token=_mapping_get(raw, "api_token", "apiToken"),
         stream_token=_mapping_get(raw, "stream_token", "streamToken"),
+        stream_attach_token=_mapping_get(
+            raw,
+            "stream_attach_token",
+            "streamAttachToken",
+        ),
+        launch_id=_mapping_get(raw, "launch_id", "launchId"),
         datasource_id=_mapping_get(raw, "datasource_id", "datasourceId"),
         euler_train_dir=_mapping_get(raw, "euler_train_dir", "eulerTrainDir"),
         run_dir=_mapping_get(raw, "run_dir", "runDir"),
@@ -484,6 +523,45 @@ def _mapping_get(
     return default
 
 
+def _extract_slurm_job_id(meta: Mapping[str, Any] | None) -> int | None:
+    if not isinstance(meta, Mapping):
+        return None
+    slurm = meta.get("slurm")
+    if not isinstance(slurm, Mapping):
+        return None
+    raw = slurm.get("job_id")
+    if isinstance(raw, bool):
+        return None
+    if isinstance(raw, int):
+        return raw if raw > 0 else None
+    if isinstance(raw, float):
+        return int(raw) if raw.is_integer() and raw > 0 else None
+    if isinstance(raw, str):
+        text = raw.strip()
+        if not text:
+            return None
+        try:
+            value = int(text, 10)
+        except ValueError:
+            return None
+        return value if value > 0 else None
+    return None
+
+
+def _extract_session_stream_attach_token(payload: Mapping[str, Any]) -> str | None:
+    run = payload.get("run")
+    if not isinstance(run, Mapping):
+        return None
+    stream_attach_token = run.get("streamAttachToken")
+    if not isinstance(stream_attach_token, str):
+        legacy_launch_id = run.get("launchId")
+        if not isinstance(legacy_launch_id, str):
+            return None
+        stream_attach_token = legacy_launch_id
+    normalized = stream_attach_token.strip()
+    return normalized or None
+
+
 def _normalize_optional_text(
     value: Any,
     *,

{euler_train-2.5.0 → euler_train-2.7.0}/euler_train.egg-info/PKG-INFO

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

{euler_train-2.5.0 → euler_train-2.7.0}/pyproject.toml

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

{euler_train-2.5.0 → euler_train-2.7.0}/tests/test_runlog.py

@@ -1488,6 +1488,162 @@ class TestSaveOutputsVariants:
         run.finish()
 
 
+# ═══════════════════════════════════════════════════════════════════════════
+#  Output manifest
+# ═══════════════════════════════════════════════════════════════════════════
+
+class TestSaveOutputsManifest:
+    def test_manifest_written_for_basic_save(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=1, step=500, rgb=dict(pred=arr))
+
+        m = _read_json(run.dir / "outputs" / "epoch_1_step_500" / "manifest.json")
+        assert m["version"] == 1
+        assert m["epoch"] == 1
+        assert m["step"] == 500
+        assert "rgb" in m["output_types"]
+        assert "pred" in m["output_types"]["rgb"]
+        run.finish()
+
+    def test_manifest_indexed_files(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+        imgs = [np.zeros((4, 4, 3), dtype=np.uint8) for _ in range(3)]
+        run.save_outputs(epoch=0, step=0, rgb=dict(pred=imgs))
+
+        slot = _read_json(
+            run.dir / "outputs" / "epoch_0_step_0" / "manifest.json",
+        )["output_types"]["rgb"]["pred"]
+        assert slot["id_mode"] == "indexed"
+        assert len(slot["files"]) == 3
+        assert slot["files"][0] == {"sample_id": 0, "filename": "0000.png", "format": "png"}
+        assert slot["files"][2]["sample_id"] == 2
+        run.finish()
+
+    def test_manifest_named_files(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+        a = np.zeros((4, 4, 3), dtype=np.uint8)
+        run.save_outputs(epoch=0, step=0, rgb=dict(pred={"scene_a": a, "scene_b": a}))
+
+        slot = _read_json(
+            run.dir / "outputs" / "epoch_0_step_0" / "manifest.json",
+        )["output_types"]["rgb"]["pred"]
+        assert slot["id_mode"] == "named"
+        ids = [f["sample_id"] for f in slot["files"]]
+        assert "scene_a" in ids
+        assert "scene_b" in ids
+        run.finish()
+
+    def test_manifest_aux_slots(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+        arr = np.ones((4, 4), dtype=np.float32)
+        run.save_outputs(epoch=0, step=0, depth=dict(aux=dict(transmission=arr)))
+
+        m = _read_json(run.dir / "outputs" / "epoch_0_step_0" / "manifest.json")
+        assert "aux/transmission" in m["output_types"]["depth"]
+        run.finish()
+
+    def test_manifest_none_slots_excluded(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, gt=None))
+
+        slots = _read_json(
+            run.dir / "outputs" / "epoch_0_step_0" / "manifest.json",
+        )["output_types"]["rgb"]
+        assert "pred" in slots
+        assert "gt" not in slots
+        run.finish()
+
+    def test_manifest_records_format_overrides(self, tmp_path):
+        run = euler_train.init(
+            dir=str(tmp_path / "r"), config={},
+            output_formats={"depth": "npz"},
+        )
+        arr = np.ones((4, 4), dtype=np.float32)
+        run.save_outputs(epoch=0, step=0, depth=dict(pred=arr))
+
+        m = _read_json(run.dir / "outputs" / "epoch_0_step_0" / "manifest.json")
+        assert m["format_overrides"] == {"depth": "npz"}
+        assert m["output_types"]["depth"]["pred"]["files"][0]["format"] == "npz"
+        run.finish()
+
+    def test_manifest_mixed_named_and_indexed(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={"x": arr}, gt=arr))
+
+        slots = _read_json(
+            run.dir / "outputs" / "epoch_0_step_0" / "manifest.json",
+        )["output_types"]["rgb"]
+        assert slots["pred"]["id_mode"] == "named"
+        assert slots["gt"]["id_mode"] == "indexed"
+        run.finish()
+
+    def test_manifest_metadata(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,
+            metadata={"dataset": "vkitti2", "split": "val"},
+            rgb=dict(pred=arr),
+        )
+
+        m = _read_json(run.dir / "outputs" / "epoch_0_step_0" / "manifest.json")
+        assert m["metadata"] == {"dataset": "vkitti2", "split": "val"}
+        run.finish()
+
+    def test_manifest_metadata_absent_when_not_provided(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))
+
+        m = _read_json(run.dir / "outputs" / "epoch_0_step_0" / "manifest.json")
+        assert "metadata" not in m
+        run.finish()
+
+    def test_manifest_metadata_requires_dataset(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+        arr = np.zeros((4, 4, 3), dtype=np.uint8)
+        with pytest.raises(ValueError, match="dataset"):
+            run.save_outputs(
+                epoch=0, step=0,
+                metadata={"split": "val"},
+                rgb=dict(pred=arr),
+            )
+        run.finish()
+
+    def test_manifest_metadata_rejects_empty_dataset(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+        arr = np.zeros((4, 4, 3), dtype=np.uint8)
+        with pytest.raises(ValueError, match="dataset"):
+            run.save_outputs(
+                epoch=0, step=0,
+                metadata={"dataset": "  "},
+                rgb=dict(pred=arr),
+            )
+        run.finish()
+
+    def test_no_manifest_when_all_none(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+        run.save_outputs(epoch=0, step=0, rgb=None, depth=None)
+
+        manifest_path = run.dir / "outputs" / "epoch_0_step_0" / "manifest.json"
+        assert not manifest_path.exists()
+        run.finish()
+
+    def test_manifest_multiple_output_types(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+        img = np.zeros((4, 4, 3), dtype=np.uint8)
+        dep = np.ones((4, 4), dtype=np.float32)
+        run.save_outputs(epoch=0, step=0, rgb=dict(pred=img), depth=dict(pred=dep))
+
+        m = _read_json(run.dir / "outputs" / "epoch_0_step_0" / "manifest.json")
+        assert m["output_types"]["rgb"]["pred"]["files"][0]["format"] == "png"
+        assert m["output_types"]["depth"]["pred"]["files"][0]["format"] == "npy"
+        run.finish()
+
+
 # ═══════════════════════════════════════════════════════════════════════════
 #  init_checkpoint_dir
 # ═══════════════════════════════════════════════════════════════════════════
@@ -1766,14 +1922,13 @@ class TestStreaming:
         assert "elapsed_sec" not in val_event["records"][0]
 
         snapshot_event = consumer.events[5]
-        assert snapshot_event["snapshot"] == {
-            "epoch": 0,
-            "step": 1,
-            "types": {
-                "depth": ["aux/transmission"],
-                "rgb": ["gt", "pred"],
-            },
-        }
+        snapshot = snapshot_event["snapshot"]
+        assert snapshot["version"] == 1
+        assert snapshot["epoch"] == 0
+        assert snapshot["step"] == 1
+        assert set(snapshot["output_types"]) == {"rgb", "depth"}
+        assert set(snapshot["output_types"]["rgb"]) == {"pred", "gt"}
+        assert "aux/transmission" in snapshot["output_types"]["depth"]
 
         checkpoint_event = consumer.events[6]
         assert checkpoint_event["checkpoint"] == {