euler-train 2.6.0__tar.gz → 2.8.0__tar.gz

{euler_train-2.6.0 → euler_train-2.8.0}/PKG-INFO

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

{euler_train-2.6.0 → euler_train-2.8.0}/README.md

@@ -49,6 +49,94 @@ 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 required whenever the package needs to negotiate its own short-lived ingest token, even if `stream_attach_token` is also provided.
+- `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`.
+
+`stream_attach_token` is only the attachment/correlation key. It does not authenticate the session request by itself. In the current implementation you still need `api_token` or `access_token` for the session handshake, unless you already have a pre-issued `stream_token`.
+
+### Dry-run connectivity check
+
+If you need to verify from a cluster node whether Euler View is reachable and whether the stream handshake would be accepted before starting a real run, the package exposes the same dry-run check used by the stream protocol:
+
+```bash
+euler-train.stream.check \
+  --api-url https://view.example.com \
+  --model-id 42 \
+  --api-key "$EULER_VIEW_API_TOKEN" \
+  --stream-attach-token "$EULER_VIEW_STREAM_ATTACH_TOKEN"
+```
+
+This command calls:
+
+- `POST /api/models/{model_id}/runs/{run_id}/stream/check`
+
+It validates:
+
+- network reachability to Euler View
+- API token validity and scope
+- model existence
+- stream attachment resolution via `stream_attach_token`, when provided
+- SLURM fallback matching via `--slurm-job-id`, when no attach token is provided
+
+Useful flags:
+
+- `--run-id`: override the dry-run run ID. If omitted, the CLI generates a temporary `stream-check-*` ID.
+- `--stream-attach-token`: test the explicit launch attachment path.
+- `--slurm-job-id`: test the fallback SLURM matching path.
+- `--datasource-id`: include the datasource hint that a real stream session would send.
+- `--euler-train-dir` and `--run-dir`: include path hints in the dry-run payload.
+- `--json`: print the raw JSON response for automation.
+
+The dry-run check does not start a run and does not mint an ingest token. It only verifies that the real session handshake would be accepted with the same request shape.
+
+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 +155,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 +169,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 +185,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 +203,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 +216,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 +234,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.6.0 → euler_train-2.8.0}/euler_train/__init__.py

@@ -12,6 +12,7 @@ from .stream import (
     OutputStream,
     OutputStreamConsumer,
     StreamContext,
+    check_stream_handshake,
 )
 
 __all__ = [
@@ -20,6 +21,7 @@ __all__ = [
     "OutputStream",
     "OutputStreamConsumer",
     "StreamContext",
+    "check_stream_handshake",
     "init",
     "Run",
     "export_architecture",

{euler_train-2.6.0 → euler_train-2.8.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
@@ -295,14 +316,17 @@ class EulerViewStreamConsumer:
             f"{self.config.base_url}/api/models/{self.config.model_id}"
             f"/runs/{quote(self._context.run_id, safe='')}/stream/session"
         )
-        session_body: dict[str, Any] = {
-            "runDir": self.config.run_dir or str(self._context.run_dir),
-            "eulerTrainDir": self.config.euler_train_dir or str(self._context.runs_dir),
-        }
-        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:
-            session_body["expiresInSec"] = self.config.session_expires_in_sec
+        session_body = _build_stream_session_body(
+            run_dir=self.config.run_dir or str(self._context.run_dir),
+            euler_train_dir=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
+            ),
+            slurm_job_id=_extract_slurm_job_id(self._context.meta),
+            datasource_id=self.config.datasource_id,
+            session_expires_in_sec=self.config.session_expires_in_sec,
+        )
 
         try:
             payload = self._post_json(
@@ -328,6 +352,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
@@ -339,44 +367,13 @@ class EulerViewStreamConsumer:
         *,
         token: str | None,
     ) -> dict[str, Any]:
-        headers = {
-            "Accept": "application/json",
-            "Content-Type": "application/json",
-        }
-        if token:
-            headers["Authorization"] = f"Bearer {token}"
-
-        request = Request(
+        return _post_json_request(
             url,
-            data=json.dumps(payload, default=_json_default).encode("utf-8"),
-            headers=headers,
-            method="POST",
+            payload,
+            token=token,
+            timeout_sec=self.config.timeout_sec,
         )
 
-        try:
-            with urlopen(request, timeout=self.config.timeout_sec) as response:
-                raw = response.read()
-        except HTTPError as exc:
-            message = _extract_http_error_message(exc)
-            raise RuntimeError(message) from exc
-        except URLError as exc:
-            reason = exc.reason if exc.reason else str(exc)
-            raise RuntimeError(str(reason)) from exc
-        except OSError as exc:
-            raise RuntimeError(str(exc)) from exc
-
-        if not raw:
-            return {}
-
-        try:
-            parsed = json.loads(raw.decode("utf-8"))
-        except json.JSONDecodeError as exc:
-            raise RuntimeError("Invalid JSON response from stream API") from exc
-
-        if isinstance(parsed, dict):
-            return parsed
-        raise RuntimeError("Unexpected stream API response payload")
-
     def _trim_pending(self) -> None:
         overflow = len(self._pending) - self.config.max_pending_events
         if overflow <= 0:
@@ -426,6 +423,111 @@ def coerce_output_stream(spec: Any) -> OutputStream | None:
     )
 
 
+def check_stream_handshake(
+    config: EulerViewStreamConfig | Mapping[str, Any],
+    *,
+    run_id: str | None = None,
+    stream_attach_token: str | None = None,
+    slurm_job_id: int | None = None,
+    datasource_id: int | None = None,
+    euler_train_dir: str | None = None,
+    run_dir: str | None = None,
+) -> dict[str, Any]:
+    if isinstance(config, Mapping):
+        resolved_config = _config_from_mapping(config)
+    elif isinstance(config, EulerViewStreamConfig):
+        resolved_config = config
+    else:
+        raise TypeError(
+            "config must be a mapping or EulerViewStreamConfig",
+        )
+
+    if resolved_config.stream_token is not None:
+        raise ValueError(
+            "stream.stream_token bypasses the session handshake; a dry-run handshake requires api_token or access_token instead",
+        )
+
+    if resolved_config.model_id is None:
+        raise ValueError("stream.model_id is required for handshake checks")
+
+    normalized_run_id = (
+        _normalize_optional_text(run_id, field_name="run_id")
+        if run_id is not None
+        else _default_stream_check_run_id()
+    )
+    if normalized_run_id is None:
+        normalized_run_id = _default_stream_check_run_id()
+    normalized_stream_attach_token = (
+        _normalize_optional_text(
+            stream_attach_token,
+            field_name="stream_attach_token",
+        )
+        if stream_attach_token is not None
+        else None
+    )
+    if (
+        normalized_stream_attach_token is not None
+        and resolved_config.stream_attach_token is not None
+        and normalized_stream_attach_token != resolved_config.stream_attach_token
+    ):
+        raise ValueError(
+            "stream_attach_token argument does not match stream.stream_attach_token",
+        )
+
+    resolved_datasource_id = (
+        _require_positive_int(
+            datasource_id,
+            field_name="datasource_id",
+            allow_none=True,
+        )
+        if datasource_id is not None
+        else resolved_config.datasource_id
+    )
+    resolved_slurm_job_id = (
+        _require_positive_int(
+            slurm_job_id,
+            field_name="slurm_job_id",
+            allow_none=True,
+        )
+        if slurm_job_id is not None
+        else None
+    )
+    resolved_euler_train_dir = (
+        _normalize_optional_text(
+            euler_train_dir,
+            field_name="euler_train_dir",
+        )
+        if euler_train_dir is not None
+        else resolved_config.euler_train_dir
+    )
+    resolved_run_dir = (
+        _normalize_optional_text(run_dir, field_name="run_dir")
+        if run_dir is not None
+        else resolved_config.run_dir
+    )
+
+    url = (
+        f"{resolved_config.base_url}/api/models/{resolved_config.model_id}"
+        f"/runs/{quote(normalized_run_id, safe='')}/stream/check"
+    )
+    payload = _build_stream_session_body(
+        run_dir=resolved_run_dir,
+        euler_train_dir=resolved_euler_train_dir,
+        stream_attach_token=(
+            normalized_stream_attach_token or resolved_config.stream_attach_token
+        ),
+        slurm_job_id=resolved_slurm_job_id,
+        datasource_id=resolved_datasource_id,
+        session_expires_in_sec=resolved_config.session_expires_in_sec,
+    )
+    return _post_json_request(
+        url,
+        payload,
+        token=resolved_config.api_token or resolved_config.access_token,
+        timeout_sec=resolved_config.timeout_sec,
+    )
+
+
 def _looks_like_consumer(value: Any) -> bool:
     return all(
         callable(getattr(value, name, None))
@@ -448,6 +550,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 +592,75 @@ 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 _build_stream_session_body(
+    *,
+    run_dir: str | None,
+    euler_train_dir: str | None,
+    stream_attach_token: str | None,
+    slurm_job_id: int | None,
+    datasource_id: int | None,
+    session_expires_in_sec: int | None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {}
+    if run_dir is not None:
+        body["runDir"] = run_dir
+    if euler_train_dir is not None:
+        body["eulerTrainDir"] = euler_train_dir
+    if stream_attach_token is not None:
+        body["streamAttachToken"] = stream_attach_token
+    if slurm_job_id is not None:
+        body["slurmJobId"] = slurm_job_id
+    if datasource_id is not None:
+        body["datasourceId"] = datasource_id
+    if session_expires_in_sec is not None:
+        body["expiresInSec"] = session_expires_in_sec
+    return body
+
+
+def _default_stream_check_run_id() -> str:
+    timestamp = datetime.utcnow().strftime("%Y%m%dT%H%M%SZ")
+    return f"stream-check-{timestamp}"
+
+
 def _normalize_optional_text(
     value: Any,
     *,
@@ -558,6 +735,52 @@ def _extract_http_error_message(error: HTTPError) -> str:
     return f"HTTP {error.code}: {error.reason}"
 
 
+def _post_json_request(
+    url: str,
+    payload: dict[str, Any],
+    *,
+    token: str | None,
+    timeout_sec: float,
+) -> dict[str, Any]:
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    request = Request(
+        url,
+        data=json.dumps(payload, default=_json_default).encode("utf-8"),
+        headers=headers,
+        method="POST",
+    )
+
+    try:
+        with urlopen(request, timeout=timeout_sec) as response:
+            raw = response.read()
+    except HTTPError as exc:
+        message = _extract_http_error_message(exc)
+        raise RuntimeError(message) from exc
+    except URLError as exc:
+        reason = exc.reason if exc.reason else str(exc)
+        raise RuntimeError(str(reason)) from exc
+    except OSError as exc:
+        raise RuntimeError(str(exc)) from exc
+
+    if not raw:
+        return {}
+
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+    except json.JSONDecodeError as exc:
+        raise RuntimeError("Invalid JSON response from stream API") from exc
+
+    if isinstance(parsed, dict):
+        return parsed
+    raise RuntimeError("Unexpected stream API response payload")
+
+
 def _to_jsonable(value: Any) -> Any:
     return json.loads(json.dumps(value, default=_json_default))
 
@@ -568,5 +791,6 @@ __all__ = [
     "OutputStream",
     "OutputStreamConsumer",
     "StreamContext",
+    "check_stream_handshake",
     "coerce_output_stream",
 ]

euler_train-2.8.0/euler_train/stream_check_cli.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from .stream import check_stream_handshake
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="euler-train.stream.check",
+        description="Dry-run the Euler View stream handshake",
+    )
+    parser.add_argument("--api-url", required=True, help="Euler View base URL")
+    parser.add_argument("--model-id", required=True, type=int, help="Euler View model ID")
+    parser.add_argument(
+        "--api-key",
+        required=True,
+        help="Euler View API token used to authorize the handshake check",
+    )
+    parser.add_argument(
+        "--run-id",
+        help="Run ID to use for the dry-run handshake. Defaults to an ephemeral stream-check ID.",
+    )
+    parser.add_argument(
+        "--stream-attach-token",
+        help="Optional explicit launch attachment token to validate",
+    )
+    parser.add_argument(
+        "--slurm-job-id",
+        type=int,
+        help="Optional SLURM job ID to test the fallback matching path",
+    )
+    parser.add_argument(
+        "--datasource-id",
+        type=int,
+        help="Optional datasource hint to include in the handshake payload",
+    )
+    parser.add_argument(
+        "--euler-train-dir",
+        help="Optional euler_train runs directory path to include in the handshake payload",
+    )
+    parser.add_argument(
+        "--run-dir",
+        help="Optional run directory path to include in the handshake payload",
+    )
+    parser.add_argument(
+        "--timeout-sec",
+        type=float,
+        default=10.0,
+        help="HTTP timeout in seconds (default: 10)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the raw JSON response instead of a human-readable summary",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        result = check_stream_handshake(
+            {
+                "base_url": args.api_url,
+                "model_id": args.model_id,
+                "api_token": args.api_key,
+                "stream_attach_token": args.stream_attach_token,
+                "datasource_id": args.datasource_id,
+                "euler_train_dir": args.euler_train_dir,
+                "run_dir": args.run_dir,
+                "timeout_sec": args.timeout_sec,
+            },
+            run_id=args.run_id,
+            slurm_job_id=args.slurm_job_id,
+        )
+    except Exception as exc:
+        if args.json:
+            print(json.dumps({"success": False, "error": str(exc)}, indent=2))
+        else:
+            print(f"Handshake check failed: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+        return 0
+
+    run = result.get("run", {})
+    print("Handshake check succeeded")
+    print(f"  model_id: {run.get('modelId')}")
+    print(f"  run_id: {run.get('runId')}")
+    print(f"  resolution: {result.get('resolution')}")
+    print(f"  stream_attach_token: {run.get('streamAttachToken')}")
+    print(f"  ingest_url: {result.get('ingestUrl')}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{euler_train-2.6.0 → euler_train-2.8.0}/euler_train.egg-info/PKG-INFO

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

{euler_train-2.6.0 → euler_train-2.8.0}/euler_train.egg-info/SOURCES.txt

@@ -10,9 +10,11 @@ euler_train/run.py
 euler_train/serialization.py
 euler_train/slurm.py
 euler_train/stream.py
+euler_train/stream_check_cli.py
 euler_train.egg-info/PKG-INFO
 euler_train.egg-info/SOURCES.txt
 euler_train.egg-info/dependency_links.txt
+euler_train.egg-info/entry_points.txt
 euler_train.egg-info/requires.txt
 euler_train.egg-info/top_level.txt
 tests/test_runlog.py

euler_train-2.8.0/euler_train.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+euler-train.stream.check = euler_train.stream_check_cli:main

{euler_train-2.6.0 → euler_train-2.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "euler-train"
-version = "2.6.0"
+version = "2.8.0"
 description = "Lightweight file-based experiment logger for PyTorch"
 requires-python = ">=3.9"
 dependencies = ["numpy", "euler-dataset-contract"]
@@ -16,5 +16,8 @@ architecture = ["onnx", "onnxruntime", "onnxsim"]
 naming = ["euler-metric-naming"]
 dev = ["pytest", "Pillow", "torch", "nvidia-ml-py", "onnx", "onnxruntime", "onnxsim"]
 
+[project.scripts]
+"euler-train.stream.check" = "euler_train.stream_check_cli:main"
+
 [tool.pytest.ini_options]
 pythonpath = ["."]

{euler_train-2.6.0 → euler_train-2.8.0}/tests/test_runlog.py

@@ -16,6 +16,7 @@ from PIL import Image
 
 import euler_train
 import euler_train.stream as stream_mod
+from euler_train.stream_check_cli import main as stream_check_cli_main
 
 # ═══════════════════════════════════════════════════════════════════════════
 #  Helpers
@@ -2053,6 +2054,121 @@ class TestStreaming:
         meta = _read_json(run.dir / "meta.json")
         assert meta["status"] == "completed"
 
+    def test_check_stream_handshake_uses_dry_run_route(
+        self,
+        monkeypatch,
+    ):
+        calls: list[dict] = []
+
+        def fake_urlopen(request, timeout=0):
+            headers = {k.lower(): v for k, v in request.header_items()}
+            body = json.loads(request.data.decode("utf-8"))
+            calls.append(
+                {
+                    "url": request.full_url,
+                    "method": request.get_method(),
+                    "headers": headers,
+                    "body": body,
+                    "timeout": timeout,
+                },
+            )
+            if request.full_url.endswith("/stream/check"):
+                return _FakeHttpResponse(
+                    {
+                        "success": True,
+                        "resolution": "stream_attach_token",
+                        "ingestUrl": "https://sync.example/api/model-run-stream/ingest",
+                        "run": {
+                            "modelId": 42,
+                            "runId": "dry-run-1",
+                            "streamAttachToken": "attach-123",
+                            "launchId": "launch-abc",
+                            "datasourceId": 7,
+                            "eulerTrainDir": "/outputs",
+                            "runDir": "/outputs/dry-run-1",
+                        },
+                    },
+                )
+            raise AssertionError(f"Unexpected URL {request.full_url}")
+
+        monkeypatch.setattr(stream_mod, "urlopen", fake_urlopen)
+
+        payload = stream_mod.check_stream_handshake(
+            {
+                "base_url": "https://sync.example",
+                "model_id": 42,
+                "api_token": "user-token",
+                "stream_attach_token": "attach-123",
+                "datasource_id": 7,
+            },
+            run_id="dry-run-1",
+        )
+
+        assert payload["success"] is True
+        assert calls == [
+            {
+                "url": "https://sync.example/api/models/42/runs/dry-run-1/stream/check",
+                "method": "POST",
+                "headers": {
+                    "accept": "application/json",
+                    "authorization": "Bearer user-token",
+                    "content-type": "application/json",
+                },
+                "body": {
+                    "streamAttachToken": "attach-123",
+                    "datasourceId": 7,
+                },
+                "timeout": 10.0,
+            },
+        ]
+
+    def test_stream_check_cli_prints_json_payload(
+        self,
+        monkeypatch,
+        capsys,
+    ):
+        def fake_urlopen(request, timeout=0):
+            if not request.full_url.endswith("/stream/check"):
+                raise AssertionError(f"Unexpected URL {request.full_url}")
+            return _FakeHttpResponse(
+                {
+                    "success": True,
+                    "resolution": "unresolved",
+                    "ingestUrl": "https://sync.example/api/model-run-stream/ingest",
+                    "run": {
+                        "modelId": 42,
+                        "runId": "dry-run-2",
+                        "streamAttachToken": None,
+                        "launchId": None,
+                        "datasourceId": None,
+                        "eulerTrainDir": None,
+                        "runDir": None,
+                    },
+                },
+            )
+
+        monkeypatch.setattr(stream_mod, "urlopen", fake_urlopen)
+
+        exit_code = stream_check_cli_main(
+            [
+                "--api-url",
+                "https://sync.example",
+                "--model-id",
+                "42",
+                "--api-key",
+                "user-token",
+                "--run-id",
+                "dry-run-2",
+                "--json",
+            ],
+        )
+
+        assert exit_code == 0
+        payload = json.loads(capsys.readouterr().out)
+        assert payload["success"] is True
+        assert payload["resolution"] == "unresolved"
+        assert payload["run"]["runId"] == "dry-run-2"
+
 
 # ═══════════════════════════════════════════════════════════════════════════
 #  lifecycle  (finish, context manager, crash)