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

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

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

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

@@ -64,9 +64,9 @@ run = euler_train.init(
     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"),
+        "model_id": 42,  # only needed for the SLURM fallback path
     },
 )
 ```
@@ -74,8 +74,8 @@ run = euler_train.init(
 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.
+- `model_id`: Euler View model that should receive this run. This is optional when `stream_attach_token` is provided, and required for the SLURM fallback path.
+- `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.
@@ -85,17 +85,52 @@ What each field is for:
 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`.
+2. When the first stream flush happens, the package requests a session from Euler View at `POST /api/model-run-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"]`.
+4. If no `stream_attach_token` is configured, the package falls back to the SLURM metadata already captured in `meta.json["slurm"]["job_id"]`. In that fallback mode, `model_id` must be configured so Euler View knows which model namespace to match against.
 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 \
+  --api-key "$EULER_VIEW_API_TOKEN" \
+  --stream-attach-token "$EULER_VIEW_STREAM_ATTACH_TOKEN"
+```
+
+This command calls `POST /api/model-run-stream/check`.
+
+It validates:
+
+- network reachability to Euler View
+- API token validity and scope
+- stream attachment resolution via `stream_attach_token`, when provided
+- model existence, when the request uses the `model_id` + `--slurm-job-id` fallback path
+- 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.
+- `--model-id`: required for the fallback SLURM matching path, optional when `--stream-attach-token` is used.
+- `--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`.
+- 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. In that mode the producer does not need to know `model_id`.
+- Under plain SLURM launches: no extra attachment config is required as long as Euler View can uniquely match the run by `slurm.job_id`, but `model_id` still has to be configured for the fallback lookup.
 - 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.

{euler_train-2.7.0 → euler_train-2.9.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.7.0 → euler_train-2.9.0}/euler_train/stream.py

@@ -11,7 +11,6 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any, Protocol
 from urllib.error import HTTPError, URLError
-from urllib.parse import quote
 from urllib.request import Request, urlopen
 
 from .serialization import _json_default
@@ -146,9 +145,9 @@ class EulerViewStreamConfig:
         )
 
         if self.stream_token is None:
-            if self.model_id is None:
+            if self.model_id is None and self.stream_attach_token is None:
                 raise ValueError(
-                    "stream.model_id is required when stream.stream_token is not provided",
+                    "stream.model_id is required when neither stream.stream_token nor stream.stream_attach_token is provided",
                 )
             if self.api_token is None and self.access_token is None:
                 raise ValueError(
@@ -312,26 +311,20 @@ class EulerViewStreamConsumer:
         if not force and now < self._next_retry_at:
             return False
 
-        session_url = (
-            f"{self.config.base_url}/api/models/{self.config.model_id}"
-            f"/runs/{quote(self._context.run_id, safe='')}/stream/session"
+        session_url = f"{self.config.base_url}/api/model-run-stream/session"
+        session_body = _build_stream_session_body(
+            run_id=self._context.run_id,
+            model_id=self.config.model_id,
+            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,
         )
-        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),
-        }
-        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:
-            session_body["expiresInSec"] = self.config.session_expires_in_sec
 
         try:
             payload = self._post_json(
@@ -372,44 +365,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:
@@ -459,6 +421,112 @@ 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",
+        )
+
+    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_stream_attach_token = (
+        normalized_stream_attach_token or resolved_config.stream_attach_token
+    )
+    if resolved_config.model_id is None and resolved_stream_attach_token is None:
+        raise ValueError(
+            "stream.model_id is required for handshake checks when stream_attach_token is not provided",
+        )
+
+    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/model-run-stream/check"
+    payload = _build_stream_session_body(
+        run_id=normalized_run_id,
+        model_id=resolved_config.model_id,
+        run_dir=resolved_run_dir,
+        euler_train_dir=resolved_euler_train_dir,
+        stream_attach_token=resolved_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))
@@ -562,6 +630,40 @@ def _extract_session_stream_attach_token(payload: Mapping[str, Any]) -> str | No
     return normalized or None
 
 
+def _build_stream_session_body(
+    *,
+    run_id: str,
+    model_id: int | None,
+    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] = {"runId": run_id}
+    if model_id is not None:
+        body["modelId"] = model_id
+    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,
     *,
@@ -636,6 +738,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))
 
@@ -646,5 +794,6 @@ __all__ = [
     "OutputStream",
     "OutputStreamConsumer",
     "StreamContext",
+    "check_stream_handshake",
     "coerce_output_stream",
 ]

euler_train-2.9.0/euler_train/stream_check_cli.py

@@ -0,0 +1,111 @@
+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",
+        type=int,
+        help="Euler View model ID. Required when using the SLURM fallback path instead of --stream-attach-token.",
+    )
+    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)
+
+    if args.model_id is None and not args.stream_attach_token:
+        parser.error("--model-id is required unless --stream-attach-token is provided")
+
+    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.7.0 → euler_train-2.9.0}/euler_train.egg-info/PKG-INFO

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

{euler_train-2.7.0 → euler_train-2.9.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.9.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.7.0 → euler_train-2.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "euler-train"
-version = "2.7.0"
+version = "2.9.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.7.0 → euler_train-2.9.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
@@ -1962,7 +1963,7 @@ class TestStreaming:
                     "timeout": timeout,
                 },
             )
-            if request.full_url.endswith("/stream/session"):
+            if request.full_url == "https://sync.example/api/model-run-stream/session":
                 return _FakeHttpResponse(
                     {
                         "token": "stream-token",
@@ -1996,12 +1997,12 @@ class TestStreaming:
         run.log({"loss": 0.25}, step=3, epoch=1)
         run.finish()
 
-        assert calls[0]["url"] == (
-            f"https://sync.example/api/models/42/runs/{run.run_id}/stream/session"
-        )
+        assert calls[0]["url"] == "https://sync.example/api/model-run-stream/session"
         assert calls[0]["method"] == "POST"
         assert calls[0]["headers"]["authorization"] == "Bearer user-token"
         assert calls[0]["body"] == {
+            "runId": run.run_id,
+            "modelId": 42,
             "runDir": str(run.dir),
             "eulerTrainDir": str(run.dir.parent),
             "datasourceId": 7,
@@ -2027,6 +2028,73 @@ class TestStreaming:
         finish_event = ingest_calls[2]["body"]["events"][0]
         assert finish_event["status"] == "completed"
 
+    def test_euler_view_http_consumer_can_handshake_without_model_id_when_attach_token_is_present(
+        self,
+        tmp_path,
+        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("/api/model-run-stream/session"):
+                return _FakeHttpResponse(
+                    {
+                        "token": "stream-token",
+                        "expiresAt": "2099-01-01T00:00:00+00:00",
+                        "ingestUrl": "https://sync.example/api/model-run-stream/ingest",
+                        "run": {
+                            "modelId": 42,
+                            "runId": "placeholder",
+                            "streamAttachToken": "attach-123",
+                        },
+                    },
+                )
+            if request.full_url.endswith("/api/model-run-stream/ingest"):
+                return _FakeHttpResponse(
+                    {
+                        "success": True,
+                        "events": [],
+                        "latestCursor": len(calls),
+                    },
+                )
+            raise AssertionError(f"Unexpected URL {request.full_url}")
+
+        monkeypatch.setattr(stream_mod, "urlopen", fake_urlopen)
+
+        run = euler_train.init(
+            dir=str(tmp_path / "r"),
+            config={"lr": 1e-3},
+            stream={
+                "base_url": "https://sync.example",
+                "api_token": "user-token",
+                "stream_attach_token": "attach-123",
+                "batch_size": 1,
+            },
+        )
+        run.log({"loss": 0.25}, step=3, epoch=1)
+        run.finish()
+
+        assert calls[0]["url"] == "https://sync.example/api/model-run-stream/session"
+        assert calls[0]["method"] == "POST"
+        assert calls[0]["headers"]["authorization"] == "Bearer user-token"
+        assert calls[0]["body"] == {
+            "runId": run.run_id,
+            "runDir": str(run.dir),
+            "eulerTrainDir": str(run.dir.parent),
+            "streamAttachToken": "attach-123",
+        }
+
     def test_stream_network_failures_do_not_break_training(
         self,
         tmp_path,
@@ -2053,6 +2121,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 == "https://sync.example/api/model-run-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",
+                "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/model-run-stream/check",
+                "method": "POST",
+                "headers": {
+                    "accept": "application/json",
+                    "authorization": "Bearer user-token",
+                    "content-type": "application/json",
+                },
+                "body": {
+                    "runId": "dry-run-1",
+                    "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 request.full_url != "https://sync.example/api/model-run-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",
+                "--api-key",
+                "user-token",
+                "--run-id",
+                "dry-run-2",
+                "--stream-attach-token",
+                "attach-123",
+                "--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)