jobdock-sdk 0.2.1rc2__tar.gz

jobdock_sdk-0.2.1rc2/.gitignore

@@ -0,0 +1,23 @@
+.env
+.env.*
+!.env.example
+bin/
+dist/
+coverage/
+web/node_modules/
+web/dist/
+*.tsbuildinfo
+sdk/python/.pytest_cache/
+sdk/python/.ruff_cache/
+sdk/python/*.egg-info/
+sdk/python/build/
+sdk/python/dist/
+__pycache__/
+*.py[cod]
+*.db
+*.db-shm
+*.db-wal
+.jobdock/
+.cache/
+.e2e/
+.tmp/

jobdock_sdk-0.2.1rc2/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: jobdock-sdk
+Version: 0.2.1rc2
+Summary: Optional telemetry SDK for jobs running in JobDock
+Author: JobDock contributors
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# JobDock Python SDK
+
+The SDK adds optional progress, scalar metrics, parameters, structured events, artifact registration, and cooperative cancellation to a JobDock job. It has no runtime dependencies outside the Python standard library.
+
+```python
+from jobdock import current_job
+
+job = current_job()
+job.progress(0.5)
+job.metric("loss", 0.42, step=10)
+
+# Units and metadata describe the series and stay stable for the attempt.
+job.metric("throughput", 128.4, step=10, unit="samples/s", metadata={"split": "train"})
+
+# Write checkpoints atomically beneath JOBDOCK_OUTPUT_DIR, then request a
+# durable, resumable synchronization. The result is True only after the server
+# confirms the complete immutable generation.
+save_checkpoint(job.output_dir / "epoch-10.pt")
+checkpoint_confirmed = job.sync(label="epoch 10", step=10, metadata={"score": 0.91}, timeout=60)
+
+if job.should_stop():
+    save_checkpoint()
+```
+
+Typed batches preserve observation order and accept explicit timezone-aware timestamps:
+
+```python
+from datetime import datetime, timezone
+from jobdock import Metric, current_job
+
+job = current_job()
+job.metrics([
+    Metric("train/loss", 0.42, step=10, timestamp=datetime.now(timezone.utc), unit="ratio", metadata={"dataset": "cifar10"}),
+    Metric("train/accuracy", 0.91, step=10, unit="ratio", metadata={"dataset": "cifar10"}),
+])
+```
+
+`unit` and `metadata` are series descriptors for one metric name and attempt. Omitted descriptor fields inherit the existing values; conflicting values are rejected as a whole batch. Use distinct names such as `train/loss` and `validation/loss` for semantically different series.
+
+Milestones can describe weighted stages. JobDock calculates global progress while retaining the current segment and upcoming stages independently for each attempt:
+
+```python
+from jobdock import Milestone
+
+job.define_milestones([
+    Milestone("prepare", weight=0.1),
+    Milestone("train", weight=0.8),
+    Milestone("evaluate", weight=0.1),
+])
+job.milestone("prepare")
+job.progress(0.5, milestone="train", step=10)
+```
+
+Confusion matrices remain structured data rather than rendered images. They support an explicit step and timestamp and are bounded to 128 classes and a 1 MiB encoded payload:
+
+```python
+job.confusion_matrix(
+    "validation",
+    [[48, 2], [3, 47]],
+    ["negative", "positive"],
+    step=10,
+)
+```
+
+The SDK exports presentation-independent `CheckpointObservation`, `ProgressObservation`, `Milestone`, and `MatrixObservation` contracts. These types contain no chart or React concepts.
+
+Outside JobDock, `current_job()` returns a no-op object. Use `current_job(required=True)` when missing execution context should be an error.
+
+## Versioning
+
+`jobdock-sdk` uses the JobDock product release tag as its only release-version
+source. A tag such as `v0.3.0` builds Python package version `0.3.0`; SemVer
+prereleases are converted deterministically to PEP 440, for example
+`v0.3.0-rc.1` becomes `0.3.0rc1`. The installed version is available as
+`jobdock.__version__` and is also used in the SDK HTTP user agent.
+
+An untagged source build has an explicit `0.0.0.dev0+g<commit>` version and is
+never indistinguishable from a release. Release automation supplies
+`JOBDOCK_RELEASE_TAG` and `JOBDOCK_PRODUCT_VERSION`; inconsistent values fail the
+package build instead of publishing mismatched artifacts.
+
+Checkpoint uploads are chunked, acknowledged, and resumed from the server's
+durable offset after a network or agent restart. A partially uploaded generation
+never replaces the last confirmed checkpoint. The latest confirmed generation
+remains downloadable for a `LOST` job from
+`GET /api/v1/jobs/{job_id}/checkpoints/latest.zip`.

jobdock_sdk-0.2.1rc2/README.md

@@ -0,0 +1,86 @@
+# JobDock Python SDK
+
+The SDK adds optional progress, scalar metrics, parameters, structured events, artifact registration, and cooperative cancellation to a JobDock job. It has no runtime dependencies outside the Python standard library.
+
+```python
+from jobdock import current_job
+
+job = current_job()
+job.progress(0.5)
+job.metric("loss", 0.42, step=10)
+
+# Units and metadata describe the series and stay stable for the attempt.
+job.metric("throughput", 128.4, step=10, unit="samples/s", metadata={"split": "train"})
+
+# Write checkpoints atomically beneath JOBDOCK_OUTPUT_DIR, then request a
+# durable, resumable synchronization. The result is True only after the server
+# confirms the complete immutable generation.
+save_checkpoint(job.output_dir / "epoch-10.pt")
+checkpoint_confirmed = job.sync(label="epoch 10", step=10, metadata={"score": 0.91}, timeout=60)
+
+if job.should_stop():
+    save_checkpoint()
+```
+
+Typed batches preserve observation order and accept explicit timezone-aware timestamps:
+
+```python
+from datetime import datetime, timezone
+from jobdock import Metric, current_job
+
+job = current_job()
+job.metrics([
+    Metric("train/loss", 0.42, step=10, timestamp=datetime.now(timezone.utc), unit="ratio", metadata={"dataset": "cifar10"}),
+    Metric("train/accuracy", 0.91, step=10, unit="ratio", metadata={"dataset": "cifar10"}),
+])
+```
+
+`unit` and `metadata` are series descriptors for one metric name and attempt. Omitted descriptor fields inherit the existing values; conflicting values are rejected as a whole batch. Use distinct names such as `train/loss` and `validation/loss` for semantically different series.
+
+Milestones can describe weighted stages. JobDock calculates global progress while retaining the current segment and upcoming stages independently for each attempt:
+
+```python
+from jobdock import Milestone
+
+job.define_milestones([
+    Milestone("prepare", weight=0.1),
+    Milestone("train", weight=0.8),
+    Milestone("evaluate", weight=0.1),
+])
+job.milestone("prepare")
+job.progress(0.5, milestone="train", step=10)
+```
+
+Confusion matrices remain structured data rather than rendered images. They support an explicit step and timestamp and are bounded to 128 classes and a 1 MiB encoded payload:
+
+```python
+job.confusion_matrix(
+    "validation",
+    [[48, 2], [3, 47]],
+    ["negative", "positive"],
+    step=10,
+)
+```
+
+The SDK exports presentation-independent `CheckpointObservation`, `ProgressObservation`, `Milestone`, and `MatrixObservation` contracts. These types contain no chart or React concepts.
+
+Outside JobDock, `current_job()` returns a no-op object. Use `current_job(required=True)` when missing execution context should be an error.
+
+## Versioning
+
+`jobdock-sdk` uses the JobDock product release tag as its only release-version
+source. A tag such as `v0.3.0` builds Python package version `0.3.0`; SemVer
+prereleases are converted deterministically to PEP 440, for example
+`v0.3.0-rc.1` becomes `0.3.0rc1`. The installed version is available as
+`jobdock.__version__` and is also used in the SDK HTTP user agent.
+
+An untagged source build has an explicit `0.0.0.dev0+g<commit>` version and is
+never indistinguishable from a release. Release automation supplies
+`JOBDOCK_RELEASE_TAG` and `JOBDOCK_PRODUCT_VERSION`; inconsistent values fail the
+package build instead of publishing mismatched artifacts.
+
+Checkpoint uploads are chunked, acknowledged, and resumed from the server's
+durable offset after a network or agent restart. A partially uploaded generation
+never replaces the last confirmed checkpoint. The latest confirmed generation
+remains downloadable for a `LOST` job from
+`GET /api/v1/jobs/{job_id}/checkpoints/latest.zip`.

jobdock_sdk-0.2.1rc2/hatch_build.py

@@ -0,0 +1,12 @@
+"""Hatch metadata hook for the product-derived SDK version."""
+
+from pathlib import Path
+from runpy import run_path
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+
+class CustomMetadataHook(MetadataHookInterface):
+    def update(self, metadata: dict) -> None:
+        versioning = run_path(str(Path(__file__).with_name("versioning.py")), run_name="jobdock_sdk_versioning")
+        metadata["version"] = versioning["resolve_build_version"]()

jobdock_sdk-0.2.1rc2/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jobdock-sdk"
+dynamic = ["version"]
+description = "Optional telemetry SDK for jobs running in JobDock"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "JobDock contributors"}]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jobdock"]
+core-metadata-version = "2.4"
+
+[tool.hatch.build.targets.sdist]
+core-metadata-version = "2.4"
+
+[tool.hatch.metadata.hooks.custom]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]

jobdock_sdk-0.2.1rc2/src/jobdock/__init__.py

@@ -0,0 +1,14 @@
+"""Public JobDock telemetry API."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("jobdock-sdk")
+except PackageNotFoundError:
+    # Running directly from a source checkout is always a development build.
+    __version__ = "0.0.0.dev0"
+
+from .client import Job, NoopJob, current_job
+from .observability import CheckpointObservation, JSONValue, MatrixObservation, Metric, Milestone, ProgressObservation
+
+__all__ = ["CheckpointObservation", "JSONValue", "Job", "MatrixObservation", "Metric", "Milestone", "NoopJob", "ProgressObservation", "__version__", "current_job"]

jobdock_sdk-0.2.1rc2/src/jobdock/client.py

@@ -0,0 +1,347 @@
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import math
+import os
+import queue
+import threading
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from datetime import datetime, timezone
+from typing import Any, Iterable, Mapping
+
+from .observability import CheckpointObservation, JSONValue, MatrixObservation, Metric, Milestone, ProgressObservation
+from . import __version__
+
+logger = logging.getLogger("jobdock")
+
+
+@dataclass(frozen=True)
+class _Message:
+    endpoint: str
+    payload: dict[str, Any]
+
+
+class NoopJob:
+    """Job context used when code runs outside JobDock."""
+
+    id: str | None = None
+    output_dir: Path = Path.cwd()
+
+    def progress(self, value: float, *, milestone: str | None = None, step: int | None = None, timestamp: datetime | None = None, metadata: Mapping[str, JSONValue] | None = None) -> None: pass
+    def define_milestones(self, items: Iterable[Milestone]) -> None: pass
+    def milestone(self, name: str, *, step: int | None = None, timestamp: datetime | None = None, metadata: Mapping[str, JSONValue] | None = None) -> None: pass
+    def matrix(self, observation: MatrixObservation) -> None: pass
+    def confusion_matrix(self, name: str, values: Iterable[Iterable[float]], labels: Iterable[str], *, step: int | None = None, timestamp: datetime | None = None, metadata: Mapping[str, JSONValue] | None = None) -> None: pass
+    def metric(self, name: str, value: float, step: int | None = None, *, timestamp: datetime | None = None, unit: str | None = None, metadata: Mapping[str, JSONValue] | None = None) -> None: pass
+    def metrics(self, items: Iterable[Metric]) -> None: pass
+    def param(self, name: str, value: str | int | float | bool) -> None: pass
+    def event(self, event_type: str, payload: dict[str, Any] | None = None) -> None: pass
+    def artifact(self, relative_path: str | os.PathLike[str]) -> Path: return Path(relative_path)
+    def sync(self, timeout: float = 30.0, *, label: str | None = None, step: int | None = None, timestamp: datetime | None = None, metadata: Mapping[str, JSONValue] | None = None) -> bool: return False
+    def should_stop(self) -> bool: return False
+    def close(self, timeout: float = 0.0) -> None: pass
+
+
+class Job:
+    """Non-blocking telemetry client for the current JobDock execution."""
+
+    def __init__(self, job_id: str, api_url: str, token: str, output_dir: Path, *, queue_size: int = 1024) -> None:
+        self.id = job_id
+        self.api_url = api_url.rstrip("/")
+        self.output_dir = output_dir.resolve()
+        self._token = token
+        self._queue: queue.Queue[_Message | None] = queue.Queue(maxsize=queue_size)
+        self._closed = threading.Event()
+        self._stop_cache = (0.0, False)
+        self._worker = threading.Thread(target=self._run, name="jobdock-telemetry", daemon=True)
+        self._worker.start()
+        atexit.register(self.close)
+
+    def progress(self, value: float, *, milestone: str | None = None, step: int | None = None, timestamp: datetime | None = None, metadata: Mapping[str, JSONValue] | None = None) -> None:
+        if not 0.0 <= value <= 1.0:
+            raise ValueError("progress must be between 0.0 and 1.0")
+        if milestone is not None and (not milestone.strip() or len(milestone.strip()) > 128):
+            raise ValueError("milestone name must contain 1-128 characters")
+        milestone = milestone.strip() if milestone is not None else None
+        observation = ProgressObservation(float(value), milestone, step, timestamp, metadata)
+        self._enqueue("progress", _observation_payload(observation, value=float(value), milestone=milestone))
+
+    def define_milestones(self, items: Iterable[Milestone]) -> None:
+        payload = []
+        seen: set[str] = set()
+        for item in items:
+            name = item.name.strip()
+            if not name or len(name) > 128 or name in seen or item.weight is not None and (item.weight <= 0 or not math.isfinite(item.weight)):
+                raise ValueError("milestone requires a name and an optional positive finite weight")
+            seen.add(name)
+            entry: dict[str, Any] = {"name": name}
+            if item.weight is not None: entry["weight"] = item.weight
+            metadata = _validated_metadata(item.metadata)
+            if metadata is not None: entry["metadata"] = metadata
+            payload.append(entry)
+        if not payload or len(payload) > 128: raise ValueError("milestones must contain 1-128 unique items")
+        self._enqueue("milestones", {"items": payload})
+
+    def milestone(self, name: str, *, step: int | None = None, timestamp: datetime | None = None, metadata: Mapping[str, JSONValue] | None = None) -> None:
+        if not name.strip() or len(name.strip()) > 128: raise ValueError("milestone name must contain 1-128 characters")
+        observation = ProgressObservation(0, name.strip(), step, timestamp, metadata)
+        self._enqueue("milestones/reached", _observation_payload(observation, milestone=name.strip()))
+
+    def matrix(self, observation: MatrixObservation) -> None:
+        values = [[float(value) for value in row] for row in observation.values]
+        labels = list(observation.labels)
+        size = len(values)
+        if not observation.name.strip() or len(observation.name.strip()) > 128 or size == 0 or size > 128 or len(labels) != size or any(len(row) != size for row in values) or any(not label or len(label) > 128 for label in labels):
+            raise ValueError("matrix requires a name, NxN values, and one label per dimension")
+        if any(not math.isfinite(value) for row in values for value in row): raise ValueError("matrix values must be finite")
+        payload = _observation_payload(observation, name=observation.name.strip(), values=values, labels=labels)
+        if len(json.dumps(payload, separators=(",", ":")).encode()) > 1 << 20: raise ValueError("matrix payload must not exceed 1 MiB")
+        self._enqueue("matrices", payload)
+
+    def confusion_matrix(self, name: str, values: Iterable[Iterable[float]], labels: Iterable[str], *, step: int | None = None, timestamp: datetime | None = None, metadata: Mapping[str, JSONValue] | None = None) -> None:
+        self.matrix(MatrixObservation(name, [list(row) for row in values], list(labels), step, timestamp, metadata))
+
+    def metric(self, name: str, value: float, step: int | None = None, *, timestamp: datetime | None = None, unit: str | None = None, metadata: Mapping[str, JSONValue] | None = None) -> None:
+        """Report one scalar metric while preserving the original call shape."""
+        self.metrics([Metric(name, value, step, timestamp, unit, metadata)])
+
+    def metrics(self, items: Iterable[Metric]) -> None:
+        """Report typed scalar metrics as one ordered, non-blocking batch."""
+        payload = [_metric_payload(item) for item in items]
+        if payload:
+            self._enqueue("metrics", {"items": payload})
+
+    def param(self, name: str, value: str | int | float | bool) -> None:
+        if not name or not isinstance(value, (str, int, float, bool)):
+            raise ValueError("parameter requires a name and scalar value")
+        self._enqueue("params", {"items": [{"name": name, "value": value}]})
+
+    def event(self, event_type: str, payload: dict[str, Any] | None = None) -> None:
+        if not event_type:
+            raise ValueError("event type is required")
+        self._enqueue("events", {"type": event_type, "payload": payload or {}})
+
+    def artifact(self, relative_path: str | os.PathLike[str]) -> Path:
+        raw_candidate = self.output_dir / relative_path
+        if raw_candidate.is_symlink():
+            raise ValueError("artifact cannot be a symbolic link")
+        candidate = raw_candidate.resolve()
+        try:
+            candidate.relative_to(self.output_dir)
+        except ValueError as exc:
+            raise ValueError("artifact must be inside JOBDOCK_OUTPUT_DIR") from exc
+        if not candidate.exists():
+            raise ValueError("artifact must exist")
+        self.event("artifact_registered", {"path": candidate.relative_to(self.output_dir).as_posix()})
+        return candidate
+
+    def should_stop(self) -> bool:
+        checked, cached = self._stop_cache
+        if time.monotonic() - checked < 2.0:
+            return cached
+        try:
+            response = self._request("GET", "stop", None, timeout=1.0)
+            cached = bool(response.get("should_stop", False))
+            self._stop_cache = (time.monotonic(), cached)
+        except Exception:
+            logger.debug("Unable to query cooperative cancellation", exc_info=True)
+        return cached
+
+    def sync(self, timeout: float = 30.0, *, label: str | None = None, step: int | None = None, timestamp: datetime | None = None, metadata: Mapping[str, JSONValue] | None = None) -> bool:
+        """Durably synchronize the current output directory as a checkpoint.
+
+        Files should be written with an atomic rename before calling this method.
+        The call is bounded and returns only after the server has confirmed the
+        complete immutable generation. A later failed sync cannot replace it.
+        """
+        if timeout <= 0:
+            raise ValueError("checkpoint sync timeout must be positive")
+        if label is not None and len(label.strip()) > 128:
+            raise ValueError("checkpoint label must contain at most 128 characters")
+        label = label.strip() if label is not None else None
+        deadline = time.monotonic() + timeout
+        try:
+            observation = CheckpointObservation(label, step, timestamp, metadata)
+            created = self._request("POST", "checkpoints", _observation_payload(observation, label=label), timeout=min(5.0, timeout))
+            sync_id = str(created["id"])
+            while time.monotonic() < deadline:
+                remaining = deadline - time.monotonic()
+                status = self._request("GET", f"checkpoints/{sync_id}", None, timeout=min(2.0, max(0.1, remaining)))
+                if status.get("status") == "CONFIRMED":
+                    return True
+                time.sleep(min(0.5, max(0.0, deadline - time.monotonic())))
+        except Exception:
+            logger.warning("JobDock checkpoint sync was not confirmed", exc_info=True)
+            return False
+        logger.warning("JobDock checkpoint sync timed out after %.1f seconds", timeout)
+        return False
+
+    def close(self, timeout: float = 2.0) -> None:
+        if self._closed.is_set():
+            return
+        self._closed.set()
+        try:
+            self._queue.put_nowait(None)
+        except queue.Full:
+            pass
+        self._worker.join(timeout=max(0.0, timeout))
+
+    def _enqueue(self, endpoint: str, payload: dict[str, Any]) -> None:
+        if self._closed.is_set():
+            return
+        try:
+            self._queue.put_nowait(_Message(endpoint, payload))
+        except queue.Full:
+            logger.warning("JobDock telemetry queue is full; dropping %s update", endpoint)
+
+    def _run(self) -> None:
+        while not self._closed.is_set() or not self._queue.empty():
+            try:
+                message = self._queue.get(timeout=0.2)
+            except queue.Empty:
+                continue
+            if message is None:
+                continue
+            batch = [message]
+            while len(batch) < 64:
+                try:
+                    next_message = self._queue.get_nowait()
+                except queue.Empty:
+                    break
+                if next_message is None:
+                    continue
+                if next_message.endpoint != message.endpoint:
+                    self._queue.put_nowait(next_message)
+                    break
+                batch.append(next_message)
+            payload = message.payload
+            if message.endpoint in {"metrics", "params"} and len(batch) > 1:
+                payload = {"items": [item for entry in batch for item in entry.payload["items"]]}
+            self._send_with_retry(message.endpoint, payload)
+
+    def _send_with_retry(self, endpoint: str, payload: dict[str, Any]) -> None:
+        for delay in (0.0, 0.25, 1.0, 2.0):
+            if delay:
+                time.sleep(delay)
+            try:
+                self._request("POST", endpoint, payload, timeout=2.0)
+                return
+            except Exception:
+                logger.debug("JobDock telemetry delivery failed", exc_info=True)
+        logger.warning("Dropping JobDock %s telemetry after bounded retries", endpoint)
+
+    def _request(self, method: str, endpoint: str, payload: dict[str, Any] | None, *, timeout: float) -> dict[str, Any]:
+        body = None if payload is None else json.dumps(payload, separators=(",", ":")).encode()
+        request = urllib.request.Request(
+            f"{self.api_url}/api/v1/job-context/{endpoint}",
+            data=body,
+            method=method,
+            headers={"Authorization": f"Bearer {self._token}", "Content-Type": "application/json", "User-Agent": f"jobdock-sdk/{__version__}"},
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                data = response.read()
+        except urllib.error.HTTPError as exc:
+            raise RuntimeError(f"JobDock API returned HTTP {exc.code}") from exc
+        return json.loads(data) if data else {}
+
+
+def current_job(*, required: bool = False) -> Job | NoopJob:
+    job_id = os.getenv("JOBDOCK_JOB_ID")
+    api_url = os.getenv("JOBDOCK_API_URL")
+    token_file = os.getenv("JOBDOCK_JOB_TOKEN_FILE")
+    output_dir = os.getenv("JOBDOCK_OUTPUT_DIR")
+    if not all((job_id, api_url, token_file, output_dir)):
+        if required:
+            raise RuntimeError("JobDock execution context is incomplete")
+        return NoopJob()
+    try:
+        token = Path(token_file).read_text(encoding="utf-8").strip()
+    except OSError as exc:
+        if required:
+            raise RuntimeError("Unable to read JOBDOCK_JOB_TOKEN_FILE") from exc
+        return NoopJob()
+    return Job(job_id, api_url, token, Path(output_dir))
+
+
+def _metric_payload(metric: Metric) -> dict[str, Any]:
+    name = metric.name.strip()
+    if not name or len(name) > 128:
+        raise ValueError("metric name must contain between 1 and 128 characters")
+    value = float(metric.value)
+    if not math.isfinite(value):
+        raise ValueError("metric value must be finite")
+    if metric.step is not None and (isinstance(metric.step, bool) or not isinstance(metric.step, int)):
+        raise ValueError("metric step must be an integer")
+    unit = metric.unit.strip() if metric.unit is not None else None
+    if unit is not None and (not unit or len(unit) > 64):
+        raise ValueError("metric unit must contain between 1 and 64 characters")
+    timestamp = metric.timestamp or datetime.now(timezone.utc)
+    if timestamp.tzinfo is None or timestamp.utcoffset() is None:
+        raise ValueError("metric timestamp must be timezone-aware")
+    metadata = _validated_metadata(metric.metadata)
+    item: dict[str, Any] = {"name": name, "value": value, "timestamp": timestamp.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")}
+    if metric.step is not None:
+        item["step"] = metric.step
+    if unit is not None:
+        item["unit"] = unit
+    if metadata is not None:
+        item["metadata"] = metadata
+    return item
+
+
+def _validated_metadata(metadata: Mapping[str, JSONValue] | None) -> dict[str, JSONValue] | None:
+    if metadata is None:
+        return None
+    normalized = dict(metadata)
+    keys = [0]
+    _validate_json_value(normalized, 1, keys)
+    encoded = json.dumps(normalized, ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode("utf-8")
+    if len(encoded) > 16 << 10:
+        raise ValueError("metric metadata must not exceed 16 KiB")
+    return normalized
+
+
+def _validate_json_value(value: JSONValue, depth: int, keys: list[int]) -> None:
+    if depth > 4:
+        raise ValueError("metric metadata nesting must not exceed four levels")
+    if isinstance(value, dict):
+        for key, child in value.items():
+            keys[0] += 1
+            if keys[0] > 64:
+                raise ValueError("metric metadata must contain at most 64 keys")
+            if not isinstance(key, str) or not key or len(key) > 128:
+                raise ValueError("metric metadata keys must contain 1-128 characters")
+            _validate_json_value(child, depth + 1, keys)
+    elif isinstance(value, list):
+        if len(value) > 64:
+            raise ValueError("metric metadata arrays must contain at most 64 items")
+        for child in value:
+            _validate_json_value(child, depth + 1, keys)
+    elif isinstance(value, str):
+        if len(value) > 1024:
+            raise ValueError("metric metadata strings must contain at most 1024 characters")
+    elif isinstance(value, bool) or value is None:
+        return
+    elif isinstance(value, (int, float)):
+        if not math.isfinite(float(value)):
+            raise ValueError("metric metadata numbers must be finite")
+    else:
+        raise ValueError("metric metadata contains an unsupported JSON value")
+
+
+def _observation_payload(observation: Any, **fields: Any) -> dict[str, Any]:
+    payload = {key: value for key, value in fields.items() if value is not None}
+    if observation.step is not None: payload["step"] = observation.step
+    timestamp = observation.timestamp or datetime.now(timezone.utc)
+    if timestamp.tzinfo is None or timestamp.utcoffset() is None: raise ValueError("observation timestamp must be timezone-aware")
+    payload["timestamp"] = timestamp.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+    metadata = _validated_metadata(observation.metadata)
+    if metadata is not None: payload["metadata"] = metadata
+    return payload

jobdock_sdk-0.2.1rc2/src/jobdock/observability.py

@@ -0,0 +1,55 @@
+"""Presentation-agnostic observability contracts for JobDock jobs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Mapping, Sequence, TypeAlias
+
+JSONScalar: TypeAlias = str | int | float | bool | None
+JSONValue: TypeAlias = JSONScalar | list["JSONValue"] | dict[str, "JSONValue"]
+Metadata: TypeAlias = Mapping[str, JSONValue]
+
+
+@dataclass(frozen=True, slots=True)
+class Metric:
+    name: str
+    value: float
+    step: int | None = None
+    timestamp: datetime | None = None
+    unit: str | None = None
+    metadata: Metadata | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CheckpointObservation:
+    label: str | None = None
+    step: int | None = None
+    timestamp: datetime | None = None
+    metadata: Metadata | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Milestone:
+    name: str
+    weight: float | None = None
+    metadata: Metadata | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ProgressObservation:
+    value: float
+    milestone: str | None = None
+    step: int | None = None
+    timestamp: datetime | None = None
+    metadata: Metadata | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class MatrixObservation:
+    name: str
+    values: Sequence[Sequence[float]]
+    labels: Sequence[str] = ()
+    step: int | None = None
+    timestamp: datetime | None = None
+    metadata: Metadata | None = None

jobdock_sdk-0.2.1rc2/tests/test_client.py

@@ -0,0 +1,136 @@
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+
+from jobdock import CheckpointObservation, Job, MatrixObservation, Metric, Milestone, NoopJob, ProgressObservation, current_job
+
+
+def test_current_job_is_noop_without_environment(monkeypatch):
+    for name in ("JOBDOCK_JOB_ID", "JOBDOCK_API_URL", "JOBDOCK_JOB_TOKEN_FILE", "JOBDOCK_OUTPUT_DIR"):
+        monkeypatch.delenv(name, raising=False)
+    assert isinstance(current_job(), NoopJob)
+    with pytest.raises(RuntimeError):
+        current_job(required=True)
+
+
+def test_progress_validation(tmp_path: Path):
+    job = Job("id", "http://127.0.0.1:1", "token", tmp_path)
+    with pytest.raises(ValueError):
+        job.progress(1.1)
+    job.close()
+
+
+def test_enriched_metrics_are_typed_ordered_and_backwards_compatible(tmp_path: Path, monkeypatch):
+    job = Job("id", "http://jobdock.test", "token", tmp_path)
+    queued = []
+    monkeypatch.setattr(job, "_enqueue", lambda endpoint, payload: queued.append((endpoint, payload)))
+    job.metric("legacy", 1.0, 3)
+    observed = datetime(2026, 8, 13, 10, 30, tzinfo=timezone(timedelta(hours=2)))
+    job.metrics([
+        Metric("loss", .4, step=4, timestamp=observed, unit="ratio", metadata={"split": "train"}),
+        Metric("accuracy", .9, step=4, unit="ratio"),
+    ])
+    assert [item["name"] for item in queued[1][1]["items"]] == ["loss", "accuracy"]
+    assert queued[0][1]["items"][0]["step"] == 3
+    assert queued[1][1]["items"][0] == {
+        "name": "loss", "value": .4, "step": 4, "timestamp": "2026-08-13T08:30:00Z",
+        "unit": "ratio", "metadata": {"split": "train"},
+    }
+    job.close()
+
+
+def test_metric_validation_rejects_unsafe_observations(tmp_path: Path):
+    job = Job("id", "http://jobdock.test", "token", tmp_path)
+    with pytest.raises(ValueError, match="timezone-aware"):
+        job.metrics([Metric("loss", 1, timestamp=datetime(2026, 1, 1))])
+    with pytest.raises(ValueError, match="finite"):
+        job.metric("loss", float("nan"))
+    with pytest.raises(ValueError, match="four levels"):
+        job.metric("loss", 1, metadata={"a": {"b": {"c": {"d": "too deep"}}}})
+    with pytest.raises(ValueError, match="16 KiB|1024"):
+        job.metric("loss", 1, metadata={"value": "x" * 17000})
+    job.close()
+
+
+def test_noop_accepts_enriched_contracts_without_consuming_iterables():
+    noop = NoopJob()
+    consumed = False
+    def observations():
+        nonlocal consumed
+        consumed = True
+        yield Metric("loss", 1)
+    noop.metric("loss", 1, timestamp=datetime.now(timezone.utc), unit="ratio", metadata={"split": "train"})
+    noop.metrics(observations())
+    assert consumed is False
+    assert CheckpointObservation(label="best").label == "best"
+    assert ProgressObservation(.5, milestone="train").milestone == "train"
+    assert Milestone("train", weight=1).weight == 1
+    assert MatrixObservation("confusion", [[1, 0], [0, 1]], ["a", "b"]).labels == ["a", "b"]
+
+
+def test_artifact_cannot_escape_output(tmp_path: Path):
+    output = tmp_path / "output"
+    output.mkdir()
+    outside = tmp_path / "outside.txt"
+    outside.write_text("unsafe")
+    job = Job("id", "http://127.0.0.1:1", "token", output)
+    with pytest.raises(ValueError):
+        job.artifact("../outside.txt")
+    job.close()
+
+
+def test_explicit_checkpoint_sync_waits_for_confirmation(tmp_path: Path, monkeypatch):
+    job = Job("id", "http://jobdock.test", "token", tmp_path)
+    responses = iter([{"id": "sync-1"}, {"status": "PENDING"}, {"status": "CONFIRMED"}])
+    calls = []
+
+    def request(method, endpoint, payload, *, timeout):
+        calls.append((method, endpoint, payload))
+        return next(responses)
+
+    monkeypatch.setattr(job, "_request", request)
+    monkeypatch.setattr("jobdock.client.time.sleep", lambda _: None)
+    assert job.sync(timeout=1.0) is True
+    assert calls[0][0:2] == ("POST", "checkpoints")
+    assert calls[0][2]["timestamp"].endswith("Z")
+    assert calls[1:] == [("GET", "checkpoints/sync-1", None), ("GET", "checkpoints/sync-1", None)]
+    job.close()
+
+
+def test_progress_milestones_matrices_and_checkpoint_context(tmp_path: Path, monkeypatch):
+    job = Job("id", "http://jobdock.test", "token", tmp_path)
+    queued = []
+    monkeypatch.setattr(job, "_enqueue", lambda endpoint, payload: queued.append((endpoint, payload)))
+    observed = datetime(2026, 8, 13, 9, 15, tzinfo=timezone.utc)
+    job.define_milestones([Milestone("prepare", .2), Milestone("train", .8, {"owner": "ml"})])
+    job.milestone("prepare", step=1, timestamp=observed)
+    job.progress(.5, milestone="train", step=5, timestamp=observed, metadata={"epoch": 1})
+    job.confusion_matrix("validation", [[8, 2], [1, 9]], ["cat", "dog"], step=5, timestamp=observed)
+    assert queued[0] == ("milestones", {"items": [{"name": "prepare", "weight": .2}, {"name": "train", "weight": .8, "metadata": {"owner": "ml"}}]})
+    assert queued[1][0] == "milestones/reached" and queued[1][1]["milestone"] == "prepare"
+    assert queued[2][0] == "progress" and queued[2][1]["value"] == .5 and queued[2][1]["milestone"] == "train"
+    assert queued[3][0] == "matrices" and queued[3][1]["values"] == [[8.0, 2.0], [1.0, 9.0]]
+
+    responses = iter([{"id": "sync-rich"}, {"status": "CONFIRMED"}])
+    calls = []
+    def request(method, endpoint, payload, *, timeout):
+        calls.append((method, endpoint, payload))
+        return next(responses)
+    monkeypatch.setattr(job, "_request", request)
+    assert job.sync(label="best", step=5, timestamp=observed, metadata={"score": .9})
+    assert calls[0][2] == {"label": "best", "step": 5, "timestamp": "2026-08-13T09:15:00Z", "metadata": {"score": .9}}
+    job.close()
+
+
+def test_rich_observation_validation_is_bounded(tmp_path: Path):
+    job = Job("id", "http://jobdock.test", "token", tmp_path)
+    with pytest.raises(ValueError, match="positive finite"):
+        job.define_milestones([Milestone("train", 0)])
+    with pytest.raises(ValueError, match="NxN"):
+        job.confusion_matrix("broken", [[1, 2]], ["cat"])
+    with pytest.raises(ValueError, match="finite"):
+        job.confusion_matrix("broken", [[float("inf")]], ["cat"])
+    with pytest.raises(ValueError, match="timezone-aware"):
+        job.progress(.5, timestamp=datetime(2026, 1, 1))
+    job.close()

jobdock_sdk-0.2.1rc2/tests/test_versioning.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from versioning import VersionError, resolve_build_version, semver_tag_to_pep440
+
+SDK_ROOT = Path(__file__).resolve().parents[1]
+
+
+@pytest.mark.parametrize(
+    ("tag", "expected"),
+    [
+        ("v0.3.0", "0.3.0"),
+        ("v0.3.0-rc.1", "0.3.0rc1"),
+        ("v1.2.3-beta.2", "1.2.3b2"),
+        ("v1.2.3-preview.4", "1.2.3.dev4+preview"),
+        ("v1.2.3-7", "1.2.3.dev7"),
+    ],
+)
+def test_semver_tag_translates_deterministically_to_pep440(tag: str, expected: str) -> None:
+    assert semver_tag_to_pep440(tag) == expected
+
+
+def test_release_inputs_must_describe_the_same_product_version(tmp_path: Path) -> None:
+    with pytest.raises(VersionError, match="does not match release tag"):
+        resolve_build_version(tmp_path, {"JOBDOCK_RELEASE_TAG": "v0.3.0", "JOBDOCK_PRODUCT_VERSION": "0.4.0"})
+    with pytest.raises(VersionError, match="does not match"):
+        resolve_build_version(tmp_path, {"GITHUB_REF_TYPE": "tag", "GITHUB_REF_NAME": "v0.3.0", "JOBDOCK_RELEASE_TAG": "v0.4.0"})
+    with pytest.raises(VersionError, match="SDK version"):
+        resolve_build_version(tmp_path, {"JOBDOCK_RELEASE_TAG": "v0.3.0-rc.1", "JOBDOCK_SDK_VERSION": "0.3.0"})
+
+
+def test_non_tag_build_has_explicit_development_version(tmp_path: Path) -> None:
+    assert resolve_build_version(tmp_path, {}).startswith("0.0.0.dev0")
+
+
+def test_built_wheel_metadata_and_public_version_match_release_tag(tmp_path: Path) -> None:
+    wheel_dir = tmp_path / "wheel"
+    env = {
+        **os.environ,
+        "GITHUB_REF_TYPE": "tag",
+        "GITHUB_REF_NAME": "v0.3.0-rc.1",
+        "JOBDOCK_RELEASE_TAG": "v0.3.0-rc.1",
+        "JOBDOCK_PRODUCT_VERSION": "0.3.0-rc.1",
+    }
+    subprocess.run(
+        [sys.executable, "-m", "pip", "wheel", ".", "--no-deps", "--wheel-dir", str(wheel_dir)],
+        cwd=SDK_ROOT,
+        env=env,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    wheel = next(wheel_dir.glob("jobdock_sdk-0.3.0rc1-*.whl"))
+    target = tmp_path / "installed"
+    subprocess.run([sys.executable, "-m", "pip", "install", "--no-deps", "--target", str(target), str(wheel)], check=True, capture_output=True, text=True)
+    output = subprocess.check_output(
+        [sys.executable, "-c", "import jobdock; print(jobdock.__version__)"],
+        env={**os.environ, "PYTHONPATH": str(target)},
+        text=True,
+    ).strip()
+    assert output == "0.3.0rc1"

jobdock_sdk-0.2.1rc2/versioning.py

@@ -0,0 +1,95 @@
+"""Derive the Python SDK version from the JobDock product release tag."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+
+SEMVER_TAG = re.compile(
+    r"^v(?P<major>0|[1-9][0-9]*)\.(?P<minor>0|[1-9][0-9]*)\.(?P<patch>0|[1-9][0-9]*)"
+    r"(?:-(?P<prerelease>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$"
+)
+KNOWN_PRERELEASES = {"a": "a", "alpha": "a", "b": "b", "beta": "b", "rc": "rc"}
+
+
+class VersionError(ValueError):
+    """Raised when release version inputs are invalid or inconsistent."""
+
+
+def semver_tag_to_pep440(tag: str) -> str:
+    match = SEMVER_TAG.fullmatch(tag.strip())
+    if not match:
+        raise VersionError("release tag must be SemVer, for example v0.3.0 or v0.3.0-rc.1")
+    base = ".".join(match.group(name) for name in ("major", "minor", "patch"))
+    prerelease = match.group("prerelease")
+    if not prerelease:
+        return base
+    identifiers = prerelease.split(".")
+    for identifier in identifiers:
+        if identifier.isdigit() and len(identifier) > 1 and identifier.startswith("0"):
+            raise VersionError("numeric prerelease identifiers must not contain leading zeroes")
+    label = identifiers[0].lower()
+    number = int(identifiers[1]) if len(identifiers) > 1 and identifiers[1].isdigit() else 0
+    remainder = identifiers[2:] if len(identifiers) > 1 and identifiers[1].isdigit() else identifiers[1:]
+    if label in KNOWN_PRERELEASES:
+        version = f"{base}{KNOWN_PRERELEASES[label]}{number}"
+        return version + _local_suffix(remainder)
+    if label.isdigit():
+        return f"{base}.dev{int(label)}" + _local_suffix(identifiers[1:])
+    return f"{base}.dev{number}" + _local_suffix([label, *remainder])
+
+
+def resolve_build_version(root: Path | None = None, environ: dict[str, str] | None = None) -> str:
+    env = os.environ if environ is None else environ
+    tag = env.get("JOBDOCK_RELEASE_TAG", "").strip()
+    github_ref_type = env.get("GITHUB_REF_TYPE", "").strip()
+    github_ref_name = env.get("GITHUB_REF_NAME", "").strip()
+    if github_ref_type == "tag":
+        if tag and tag != github_ref_name:
+            raise VersionError(f"JOBDOCK_RELEASE_TAG {tag!r} does not match GitHub tag {github_ref_name!r}")
+        tag = github_ref_name
+    elif github_ref_type and tag:
+        raise VersionError("a release version cannot be built from a non-tag GitHub ref")
+    if not tag:
+        tag = _exact_git_tag(root or Path(__file__).resolve().parents[2])
+    if tag:
+        python_version = semver_tag_to_pep440(tag)
+        product_version = env.get("JOBDOCK_PRODUCT_VERSION", "").strip()
+        if product_version and product_version != tag.removeprefix("v"):
+            raise VersionError(f"product version {product_version!r} does not match release tag {tag!r}")
+        expected = env.get("JOBDOCK_SDK_VERSION", "").strip()
+        if expected and expected != python_version:
+            raise VersionError(f"SDK version {expected!r} does not match {tag!r} ({python_version})")
+        return python_version
+    return _development_version(root or Path(__file__).resolve().parents[2])
+
+
+def _exact_git_tag(root: Path) -> str:
+    result = subprocess.run(
+        ["git", "describe", "--tags", "--exact-match", "--match", "v[0-9]*"],
+        cwd=root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def _development_version(root: Path) -> str:
+    result = subprocess.run(
+        ["git", "rev-parse", "--short=12", "HEAD"], cwd=root, capture_output=True, text=True, check=False
+    )
+    revision = re.sub(r"[^0-9a-f]", "", result.stdout.lower())
+    return f"0.0.0.dev0+g{revision}" if revision else "0.0.0.dev0"
+
+
+def _local_suffix(identifiers: list[str]) -> str:
+    normalized = [re.sub(r"[^0-9a-z]+", ".", item.lower()).strip(".") for item in identifiers]
+    normalized = [item for item in normalized if item]
+    return "+" + ".".join(normalized) if normalized else ""
+
+
+if __name__ == "__main__":
+    print(resolve_build_version())