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

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

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

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

@@ -75,7 +75,7 @@ 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.
+- `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.
@@ -91,6 +91,43 @@ How the handshake works:
 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(...)`.

{euler_train-2.7.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.7.0 → euler_train-2.8.0}/euler_train/stream.py

@@ -316,22 +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),
-        }
-        stream_attach_token = (
-            self.config.stream_attach_token or self._resolved_stream_attach_token
+        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,
         )
-        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 +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:
@@ -459,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))
@@ -562,6 +631,36 @@ def _extract_session_stream_attach_token(payload: Mapping[str, Any]) -> str | No
     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,
     *,
@@ -636,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))
 
@@ -646,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.7.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.7.0
+Version: 2.8.0
 Summary: Lightweight file-based experiment logger for PyTorch
 Requires-Python: >=3.9
 Requires-Dist: numpy

{euler_train-2.7.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.7.0 → euler_train-2.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "euler-train"
-version = "2.7.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.7.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)