o41-metrics-api 0.1.0__py3-none-any.whl

o41_metrics_api/__init__.py

@@ -0,0 +1,44 @@
+"""Python client for the 041 Metrics v2 API.
+
+Use :class:`Metrics` to find and organize folders and experiments, read one
+experiment's record, catalog, annotations, and series, and send any v2 org
+event. For analysis across many experiments use ``o41-metrics-duckdb``; to
+record training and evaluation runs use ``o41-metrics-collector``.
+"""
+
+from o41_metrics_api.client import Experiment, ExperimentRun, Folder, Metrics
+from o41_metrics_api.errors import (
+    MetricsAuthError,
+    MetricsError,
+    MetricsNotFound,
+)
+from o41_metrics_api.models import (
+    Annotation,
+    AuthOrganization,
+    AuthStatus,
+    CatalogSeries,
+    ExperimentError,
+    ExperimentInfo,
+    ExperimentStatus,
+    MetricPoint,
+    Series,
+)
+
+__all__ = [
+    "Annotation",
+    "AuthOrganization",
+    "AuthStatus",
+    "CatalogSeries",
+    "Experiment",
+    "ExperimentError",
+    "ExperimentInfo",
+    "ExperimentRun",
+    "ExperimentStatus",
+    "Folder",
+    "MetricPoint",
+    "Metrics",
+    "MetricsAuthError",
+    "MetricsError",
+    "MetricsNotFound",
+    "Series",
+]

o41_metrics_api/_auth.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlparse
+
+from o41_metrics_api.errors import MetricsAuthError
+
+DEFAULT_HOST = "https://metrics.041.io"
+API_KEY_ENV = "O41_METRICS_API_KEY"
+HOST_ENV = "O41_METRICS_HOST"
+
+
+@dataclass(frozen=True)
+class Credentials:
+    api_key: str
+    host: str
+
+
+def _env(name: str) -> str:
+    """Read an ``O41_METRICS_`` variable, else its pre-rename ``SYVAIN_METRICS_``
+    name."""
+    legacy = name.replace("O41_METRICS_", "SYVAIN_METRICS_", 1)
+    return os.environ.get(name, "").strip() or os.environ.get(legacy, "").strip()
+
+
+def cli_auth_path() -> Path:
+    """Return the file written by ``o41-metrics auth login``, else the one the
+    older ``syvain-metrics`` CLI wrote."""
+    config_home = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(config_home).expanduser() if config_home else Path.home() / ".config"
+    path = root / "o41-metrics" / "auth.json"
+    legacy = root / "syvain-metrics" / "auth.json"
+    return legacy if not path.exists() and legacy.exists() else path
+
+
+def normalize_host(value: str) -> str:
+    """Return a plain HTTP(S) origin with no path, query, or fragment."""
+    parsed = urlparse(value.strip())
+    if (
+        parsed.scheme not in {"http", "https"}
+        or parsed.netloc == ""
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.path not in {"", "/"}
+        or parsed.params
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise MetricsAuthError(
+            f"Metrics host must be a plain HTTP(S) origin: {value!r}"
+        )
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+def _read_cli_login() -> tuple[str, str]:
+    path = cli_auth_path()
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as error:
+        raise MetricsAuthError(
+            f"No Metrics API key: pass api_key, set {API_KEY_ENV}, "
+            "or run `o41-metrics auth login`."
+        ) from error
+    except json.JSONDecodeError as error:
+        raise MetricsAuthError(
+            f"Metrics CLI login is not valid JSON: {path}"
+        ) from error
+    api_key = raw.get("apiKey") if isinstance(raw, dict) else None
+    if not isinstance(api_key, str) or not api_key:
+        raise MetricsAuthError(f"Metrics CLI login has no apiKey: {path}")
+    host = raw.get("host")
+    return api_key, host if isinstance(host, str) else ""
+
+
+def resolve_credentials(api_key: str | None, host: str | None) -> Credentials:
+    """Resolve like the CLI: argument, then environment, then the saved login."""
+    key = (api_key or "").strip() or _env(API_KEY_ENV)
+    login_host = ""
+    if not key:
+        key, login_host = _read_cli_login()
+    chosen_host = (
+        (host or "").strip() or _env(HOST_ENV) or login_host.strip() or DEFAULT_HOST
+    )
+    return Credentials(api_key=key, host=normalize_host(chosen_host))

o41_metrics_api/_transport.py

@@ -0,0 +1,302 @@
+"""HTTP transport for the v2 event API: envelopes, replies, streams, retries."""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable, Iterable, Iterator, Mapping
+from importlib.metadata import PackageNotFoundError, version as package_version
+from typing import Protocol, cast
+from uuid import uuid4
+
+import niquests
+from pydantic import JsonValue
+
+from o41_metrics_api._auth import Credentials
+from o41_metrics_api.errors import MetricsError
+
+type JsonObject = dict[str, JsonValue]
+
+CLIENT_NAME = "o41-metrics-api"
+RETRY_ATTEMPTS = 4
+RETRY_BACKOFF_SECONDS = 0.5
+
+
+def _package_version() -> str:
+    try:
+        return package_version(CLIENT_NAME)
+    except PackageNotFoundError:
+        return "0+unknown"
+
+
+CLIENT_VERSION = _package_version()
+
+
+class HttpResponse(Protocol):
+    @property
+    def status_code(self) -> int | None: ...
+
+    def json(self) -> object: ...
+
+    def iter_lines(self) -> Iterable[bytes | str]: ...
+
+    def close(self) -> None: ...
+
+
+type HttpRequest = Callable[..., HttpResponse]
+
+
+def envelope(event: str, data: Mapping[str, JsonValue]) -> JsonObject:
+    return {"messageId": str(uuid4()), "event": event, "data": dict(data)}
+
+
+def invalid_response(message: str) -> MetricsError:
+    return MetricsError("invalid_response", message)
+
+
+def reply_error(reply: JsonObject) -> MetricsError | None:
+    """Turns a ``syvain.v2.error`` reply into an exception, otherwise None."""
+    if reply.get("event") != "syvain.v2.error":
+        return None
+    data = reply.get("data")
+    if not isinstance(data, dict):
+        return invalid_response("Error reply has no data.")
+    status = data.get("status")
+    details = data.get("details")
+    return MetricsError(
+        str(data.get("code", "error")),
+        str(data.get("message", "")),
+        status=status if isinstance(status, int) else None,
+        retryable=data.get("retryable") is True,
+        details=details if isinstance(details, dict) else None,
+    )
+
+
+def reply_data(reply: JsonObject, expected: str) -> JsonObject:
+    """Returns the data of an expected reply or raises its error."""
+    error = reply_error(reply)
+    if error is not None:
+        raise error
+    if reply.get("event") != expected:
+        raise invalid_response(f"Expected {expected}, got {reply.get('event')}.")
+    data = reply.get("data")
+    if not isinstance(data, dict):
+        raise invalid_response(f"{expected} reply has no data object.")
+    return data
+
+
+def with_retry[T](operation: Callable[[], T]) -> T:
+    """Runs an operation that is safe to repeat, retrying retryable failures."""
+    for attempt in range(RETRY_ATTEMPTS):
+        try:
+            return operation()
+        except MetricsError as error:
+            if not error.retryable or attempt == RETRY_ATTEMPTS - 1:
+                raise
+            time.sleep(RETRY_BACKOFF_SECONDS * 2**attempt)
+    raise AssertionError("unreachable")
+
+
+def _json_body(response: HttpResponse, what: str) -> object:
+    """Parses a 2xx body; a garbled body is treated as a transient failure."""
+    try:
+        return response.json()
+    except ValueError as error:
+        raise MetricsError(
+            "transport_error",
+            f"{what} returned malformed JSON: {error}",
+            retryable=True,
+        ) from error
+
+
+class Transport:
+    def __init__(
+        self,
+        credentials: Credentials,
+        *,
+        timeout: float,
+        request: HttpRequest | None,
+    ) -> None:
+        self.api_key = credentials.api_key
+        self.host = credentials.host
+        self.timeout = timeout
+        self._session: niquests.Session | None = None
+        if request is None:
+            self._session = niquests.Session()
+            self._request = cast(HttpRequest, self._session.request)
+        else:
+            self._request = request
+
+    def close(self) -> None:
+        if self._session is not None:
+            self._session.close()
+            self._session = None
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        bearer: str | None,
+        body: object = None,
+        accept: str = "application/json",
+        stream: bool = False,
+    ) -> HttpResponse:
+        headers = {
+            "authorization": f"Bearer {bearer or self.api_key}",
+            "accept": accept,
+            "user-agent": f"{CLIENT_NAME}/{CLIENT_VERSION}",
+            "x-syvain-client": CLIENT_NAME,
+            "x-syvain-client-version": CLIENT_VERSION,
+        }
+        if body is not None:
+            headers["content-type"] = "application/json"
+        try:
+            response = self._request(
+                method,
+                f"{self.host}{path}",
+                headers=headers,
+                data=None if body is None else json.dumps(body, allow_nan=False),
+                timeout=self.timeout,
+                stream=stream,
+            )
+        except niquests.exceptions.RequestException as error:
+            raise MetricsError(
+                "transport_error", f"{method} {path}: {error}", retryable=True
+            ) from error
+        status = response.status_code or 0
+        if 200 <= status < 300:
+            return response
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+        finally:
+            response.close()
+        message = "request failed"
+        if isinstance(payload, dict) and isinstance(payload.get("error"), dict):
+            error_body = payload["error"]
+            message = str(error_body.get("message", message))
+            if error_body.get("details"):
+                message = f"{message}: {error_body['details']}"
+        raise MetricsError(
+            "http_error",
+            f"{method} {path} returned HTTP {status}: {message}",
+            status=status,
+            retryable=status == 429 or status >= 500,
+        )
+
+    def get(self, path: str) -> JsonValue:
+        """GETs a plain REST route and unwraps its ``{data, error}`` body."""
+        payload = _json_body(self._send("GET", path, bearer=None), f"GET {path}")
+        if not isinstance(payload, dict) or "data" not in payload:
+            raise invalid_response(f"GET {path} returned no data envelope.")
+        return cast(JsonValue, payload["data"])
+
+    def post_events(
+        self, path: str, events: list[JsonObject], *, bearer: str | None = None
+    ) -> list[JsonObject]:
+        """POSTs a batch of envelopes; replies come back in request order."""
+        response = self._send("POST", path, bearer=bearer, body=events)
+        replies = _json_body(response, f"POST {path}")
+        if not isinstance(replies, list) or len(replies) != len(events):
+            raise invalid_response(f"POST {path} returned the wrong number of replies.")
+        for event, reply in zip(events, replies, strict=True):
+            if (
+                not isinstance(reply, dict)
+                or reply.get("correlationId") != event["messageId"]
+            ):
+                raise invalid_response(f"POST {path} returned an uncorrelated reply.")
+        return cast(list[JsonObject], replies)
+
+    def _stream_replies(self, request: JsonObject) -> Iterator[JsonObject]:
+        """Yields the correlated NDJSON replies of one series query stream.
+
+        Raises a retryable ``transport_error`` when the stream ends; callers
+        return once they see their final record.
+        """
+        response = self._send(
+            "POST",
+            "/api/v2/query/series",
+            bearer=None,
+            body=request,
+            accept="application/x-ndjson",
+            stream=True,
+        )
+        try:
+            for raw_line in response.iter_lines():
+                line = raw_line.decode() if isinstance(raw_line, bytes) else raw_line
+                if not line.strip():
+                    continue
+                try:
+                    reply = json.loads(line)
+                except ValueError as error:
+                    raise MetricsError(
+                        "transport_error",
+                        f"Series stream returned a malformed record: {error}",
+                        retryable=True,
+                    ) from error
+                if (
+                    not isinstance(reply, dict)
+                    or reply.get("correlationId") != request["messageId"]
+                ):
+                    raise invalid_response(
+                        "Series stream returned an uncorrelated record."
+                    )
+                yield cast(JsonObject, reply)
+        except niquests.exceptions.RequestException as error:
+            raise MetricsError(
+                "transport_error", f"Series stream failed: {error}", retryable=True
+            ) from error
+        finally:
+            response.close()
+        raise MetricsError(
+            "transport_error", "Series stream ended before completion.", retryable=True
+        )
+
+    def stream_experiment_series(self, data: JsonObject) -> dict[str, list[JsonObject]]:
+        """Reads many series of one experiment; returns data records by series name.
+
+        Every series the server reports is present, possibly with no records.
+        Partial data is never returned: an error record, EOF before ``done``, or
+        counts that disagree with the records raise.
+        """
+        request = envelope("syvain.v2.query.experimentseries", data)
+        records: dict[str, list[JsonObject]] = {}
+        points: dict[str, int] = {}
+        finished: set[str] = set()
+        for reply in self._stream_replies(request):
+            event = reply.get("event")
+            if event == "syvain.v2.query.experimentseries.done":
+                done = reply_data(reply, "syvain.v2.query.experimentseries.done")
+                if (
+                    done.get("series") != len(finished)
+                    or finished != set(records)
+                    or done.get("batches") != sum(map(len, records.values()))
+                    or done.get("points") != sum(points.values())
+                ):
+                    raise invalid_response(
+                        "Series stream counts do not match its data."
+                    )
+                return records
+            if event == "syvain.v2.query.experimentseries.series":
+                summary = reply_data(reply, "syvain.v2.query.experimentseries.series")
+                name = str(summary["seriesName"])
+                if (
+                    name in finished
+                    or summary.get("batches") != len(records.setdefault(name, []))
+                    or summary.get("points") != points.get(name, 0)
+                ):
+                    raise invalid_response(
+                        f"Series stream counts for {name!r} do not match its data."
+                    )
+                finished.add(name)
+                continue
+            batch = reply_data(reply, "syvain.v2.query.series.data")
+            name = str(batch["seriesName"])
+            if name in finished:
+                raise invalid_response(f"Series {name!r} has data after its summary.")
+            values = cast(dict[str, list[JsonValue]], batch["data"])["value"]
+            points[name] = points.get(name, 0) + len(values)
+            records.setdefault(name, []).append(batch)
+        raise AssertionError("unreachable")