robotrace-dev 0.1.0a2__py3-none-any.whl

robotrace/__init__.py

@@ -0,0 +1,219 @@
+"""RoboTrace — observability and evals for AI robots.
+
+The public API in 30 seconds:
+
+    import robotrace as rt
+
+    # 1. Quickstart — one call per run.
+    rt.init(api_key="rt_…", base_url="https://app.robotrace.dev")
+    rt.log_episode(
+        name="pick_and_place v3 morning warmup",
+        policy_version="pap-v3.2.1",
+        env_version="halcyon-cell-rev4",
+        git_sha="abc1234",
+        seed=8124,
+        video="/tmp/run.mp4",
+        sensors="/tmp/sensors.bin",
+        actions="/tmp/actions.parquet",
+        duration_s=47.2,
+        fps=30,
+        metadata={"task": "pick_and_place"},
+    )
+
+    # 2. Streaming — explicit control of the lifecycle.
+    with rt.start_episode(name="…", policy_version="…") as ep:
+        ep.upload_video("/tmp/run.mp4")
+        # auto-finalize: ready on clean exit, failed on exception.
+
+    # 3. Multiple deployments at once — explicit Client.
+    with rt.Client(api_key="…", base_url="…") as client:
+        client.log_episode(...)
+
+`log_episode` is the **sacred** signature per AGENTS.md — once 1.0
+ships, breakages require a major bump and at least one minor of
+deprecation warnings.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from ._version import __version__
+from .client import (
+    ENV_API_KEY,
+    ENV_BASE_URL,
+    Client,
+    EpisodeSource,
+)
+from .episode import (
+    ArtifactKind,
+    Episode,
+    EpisodeFinalStatus,
+    UploadUrl,
+)
+from .errors import (
+    APIError,
+    AuthError,
+    ConfigurationError,
+    ConflictError,
+    NotFoundError,
+    RobotraceError,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+
+__all__ = [
+    "__version__",
+    # Public types
+    "Client",
+    "Episode",
+    "UploadUrl",
+    "ArtifactKind",
+    "EpisodeSource",
+    "EpisodeFinalStatus",
+    # Errors
+    "RobotraceError",
+    "ConfigurationError",
+    "TransportError",
+    "APIError",
+    "AuthError",
+    "NotFoundError",
+    "ConflictError",
+    "ValidationError",
+    "ServerError",
+    # Top-level convenience (backed by the default client)
+    "init",
+    "close",
+    "start_episode",
+    "log_episode",
+    # Env-var names exposed for tooling that wants to validate them
+    "ENV_API_KEY",
+    "ENV_BASE_URL",
+]
+
+# ── module-level "default client" plumbing ──────────────────────────
+#
+# Mirrors what `requests.get(...)` does — convenient for scripts, but
+# we explicitly support and document `Client(...)` for tests and any
+# multi-deployment setup. The default client is constructed lazily on
+# first use, so importing `robotrace` never hits the network or
+# requires env vars.
+
+_default_client: Client | None = None
+
+
+def init(
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    timeout: float | None = None,
+) -> None:
+    """Configure the module-level default Client.
+
+    Calling this twice rebuilds the client; the previous one (if any)
+    is closed first. Safe to call from process startup.
+    """
+    global _default_client
+    if _default_client is not None:
+        try:
+            _default_client.close()
+        except Exception:
+            pass
+    _default_client = Client(api_key=api_key, base_url=base_url, timeout=timeout)
+
+
+def close() -> None:
+    """Close the module-level default client. Safe to call twice."""
+    global _default_client
+    if _default_client is not None:
+        try:
+            _default_client.close()
+        finally:
+            _default_client = None
+
+
+def _ensure_default_client() -> Client:
+    """Lazy-construct the default client from env vars on first use.
+
+    Lets users skip the explicit `init(...)` call when they've set
+    `ROBOTRACE_API_KEY` / `ROBOTRACE_BASE_URL` (the common case for
+    CI-driven episode logging from a robot rig).
+    """
+    global _default_client
+    if _default_client is None:
+        _default_client = Client()
+    return _default_client
+
+
+def start_episode(
+    *,
+    name: str | None = None,
+    source: EpisodeSource = "real",
+    robot: str | None = None,
+    policy_version: str | None = None,
+    env_version: str | None = None,
+    git_sha: str | None = None,
+    seed: int | None = None,
+    fps: float | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    artifacts: Sequence[ArtifactKind] = ("video", "sensors", "actions"),
+) -> Episode:
+    """Open a new run on the configured deployment. See `Client.start_episode`."""
+    return _ensure_default_client().start_episode(
+        name=name,
+        source=source,
+        robot=robot,
+        policy_version=policy_version,
+        env_version=env_version,
+        git_sha=git_sha,
+        seed=seed,
+        fps=fps,
+        metadata=metadata,
+        artifacts=artifacts,
+    )
+
+
+def log_episode(
+    *,
+    name: str | None = None,
+    source: EpisodeSource = "real",
+    robot: str | None = None,
+    policy_version: str | None = None,
+    env_version: str | None = None,
+    git_sha: str | None = None,
+    seed: int | None = None,
+    video: str | Path | None = None,
+    sensors: str | Path | None = None,
+    actions: str | Path | None = None,
+    duration_s: float | None = None,
+    fps: float | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    status: EpisodeFinalStatus = "ready",
+) -> Episode:
+    """Log a complete episode in one call. See `Client.log_episode`.
+
+    This is the **sacred** signature per AGENTS.md. Don't change it
+    without bumping a major version and shipping deprecation warnings
+    for at least one minor first.
+    """
+    return _ensure_default_client().log_episode(
+        name=name,
+        source=source,
+        robot=robot,
+        policy_version=policy_version,
+        env_version=env_version,
+        git_sha=git_sha,
+        seed=seed,
+        video=video,
+        sensors=sensors,
+        actions=actions,
+        duration_s=duration_s,
+        fps=fps,
+        metadata=metadata,
+        status=status,
+    )
+
+

robotrace/_credentials.py

@@ -0,0 +1,262 @@
+"""On-disk credentials store for the `robotrace` CLI.
+
+The CLI's `login` command writes a small TOML file at
+``~/.robotrace/credentials`` that the Python SDK auto-loads when
+neither an explicit `api_key=` kwarg nor the `ROBOTRACE_API_KEY`
+environment variable is set. The same file backs `whoami` and
+`logout`.
+
+Format
+------
+
+::
+
+    [default]
+    api_key   = "rt_…"
+    base_url  = "https://app.robotrace.dev"
+    client_id = "<uuid>"
+    user_email = "art@robotrace.dev"
+    written_at = "2026-05-04T20:08:14Z"
+
+We support **profiles** in case a single workstation talks to more
+than one deployment (production + a staging cell). The MVP only
+reads/writes ``[default]``; the file format leaves room to extend
+without breaking older SDKs that ignore unknown profiles.
+
+Security
+--------
+
+The file holds a long-lived API key, so the writer enforces
+``chmod 0600`` after writing. We never log the key value. Reads
+fail loudly if the file is world-readable on systems that ship a
+strict ``UMASK`` policy — the user can re-run ``robotrace login``
+and the file will be re-created with the right perms.
+
+Cross-platform notes
+--------------------
+
+* On POSIX we ``os.chmod`` to 0600 after a fresh write.
+* On Windows ``os.chmod`` is largely a no-op for the read/write/
+  execute bits we care about, so we settle for storing in the
+  user's profile directory and rely on filesystem ACLs there.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+# tomllib only landed in 3.11; we still support 3.10 per pyproject.
+if sys.version_info >= (3, 11):
+    import tomllib as _tomllib  # noqa: PLC0415
+else:  # pragma: no cover — exercised on 3.10
+    _tomllib = None  # type: ignore[assignment]
+
+
+CREDENTIALS_DIR_NAME = ".robotrace"
+CREDENTIALS_FILE_NAME = "credentials"
+DEFAULT_PROFILE = "default"
+
+
+@dataclass
+class StoredCredentials:
+    """One profile's worth of credentials."""
+
+    api_key: str
+    base_url: str
+    client_id: str | None = None
+    user_email: str | None = None
+    written_at: str | None = None
+
+
+def credentials_path() -> Path:
+    """Resolve the path to the credentials file.
+
+    Uses ``$ROBOTRACE_HOME`` when set (handy for tests and CI), then
+    falls back to ``~/.robotrace`` on every platform — matches the
+    convention popular among devtools (``~/.aws``, ``~/.docker``,
+    ``~/.kube``).
+    """
+    override = os.environ.get("ROBOTRACE_HOME")
+    if override:
+        return Path(override) / CREDENTIALS_FILE_NAME
+    return Path.home() / CREDENTIALS_DIR_NAME / CREDENTIALS_FILE_NAME
+
+
+def write_credentials(creds: StoredCredentials, *, profile: str = DEFAULT_PROFILE) -> Path:
+    """Persist `creds` under `profile` in the credentials file.
+
+    Returns the absolute path written. Creates the parent dir with
+    mode 0700, then writes the file with mode 0600. Raises on any
+    filesystem error — login is the last step of the flow, so a
+    failure to persist is worth surfacing loudly.
+    """
+    path = credentials_path()
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+
+    existing = _read_all_profiles(path)
+    existing[profile] = {
+        "api_key": creds.api_key,
+        "base_url": creds.base_url,
+        "client_id": creds.client_id,
+        "user_email": creds.user_email,
+        "written_at": creds.written_at or _now_iso(),
+    }
+
+    _atomic_write_toml(path, existing)
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        # On Windows / odd filesystems chmod can fail; the dir
+        # permission and user-profile location are our backstop.
+        pass
+    return path
+
+
+def read_credentials(*, profile: str = DEFAULT_PROFILE) -> StoredCredentials | None:
+    """Load `profile` from the credentials file, or `None` if absent.
+
+    Returns `None` for any of: missing dir, missing file, profile
+    not present, malformed file. The SDK falls back to env-var auth
+    in those cases — we never want a corrupt creds file to surface
+    as a confusing "API key not provided" error.
+    """
+    path = credentials_path()
+    if not path.is_file():
+        return None
+    try:
+        all_profiles = _read_all_profiles(path)
+    except Exception:
+        return None
+    raw = all_profiles.get(profile)
+    if not isinstance(raw, dict):
+        return None
+    api_key = raw.get("api_key")
+    base_url = raw.get("base_url")
+    if not isinstance(api_key, str) or not isinstance(base_url, str):
+        return None
+    if not api_key or not base_url:
+        return None
+    client_id = raw.get("client_id")
+    user_email = raw.get("user_email")
+    written_at = raw.get("written_at")
+    return StoredCredentials(
+        api_key=api_key,
+        base_url=base_url,
+        client_id=client_id if isinstance(client_id, str) else None,
+        user_email=user_email if isinstance(user_email, str) else None,
+        written_at=written_at if isinstance(written_at, str) else None,
+    )
+
+
+def delete_credentials(*, profile: str = DEFAULT_PROFILE) -> bool:
+    """Remove `profile` from the credentials file. Returns True if
+    something was removed, False otherwise.
+
+    If the resulting file has no profiles left, the file (and its
+    parent dir, if empty) are deleted to leave a clean filesystem.
+    """
+    path = credentials_path()
+    if not path.is_file():
+        return False
+    try:
+        existing = _read_all_profiles(path)
+    except Exception:
+        return False
+    if profile not in existing:
+        return False
+    existing.pop(profile)
+    if existing:
+        _atomic_write_toml(path, existing)
+        try:
+            os.chmod(path, 0o600)
+        except OSError:
+            pass
+    else:
+        try:
+            path.unlink()
+        except OSError:
+            return False
+        try:
+            path.parent.rmdir()
+        except OSError:
+            # Dir not empty (other tools' creds in there) — fine.
+            pass
+    return True
+
+
+# ── internals ────────────────────────────────────────────────────────
+
+
+def _now_iso() -> str:
+    return datetime.now(tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _read_all_profiles(path: Path) -> dict[str, object]:
+    """Parse the whole credentials file into a {profile: {...}} dict.
+
+    Tolerant of either canonical TOML (which `_atomic_write_toml`
+    produces) or a fallback JSON-encoded body that older SDKs
+    might have written. Returns ``{}`` on parse errors so the
+    caller can treat it as a fresh write.
+    """
+    if _tomllib is not None:
+        try:
+            with path.open("rb") as fh:
+                return dict(_tomllib.load(fh))
+        except Exception:
+            # fall through to JSON
+            pass
+
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+
+    # Last-resort JSON parser for environments without tomllib that
+    # somehow ended up with a JSON-formatted creds file.
+    try:
+        loaded = json.loads(text)
+    except Exception:
+        return {}
+    return dict(loaded) if isinstance(loaded, dict) else {}
+
+
+def _atomic_write_toml(path: Path, data: dict[str, object]) -> None:
+    """Write `data` to `path` as TOML, atomically.
+
+    We don't take a hard dep on a TOML *writer* (the stdlib gained
+    one in 3.11 only as ``tomllib`` for *reading*). Hand-rolling the
+    minimal subset we use — ``[section]`` headers and ``key = "str"``
+    pairs — avoids a third-party dep on the SDK install path.
+    """
+    lines: list[str] = ["# robotrace credentials\n# managed by `robotrace login` — do not commit.\n\n"]
+    # Stable ordering keeps diffs readable when the user opens the
+    # file out of curiosity.
+    for profile in sorted(data.keys()):
+        section = data[profile]
+        if not isinstance(section, dict):
+            continue
+        lines.append(f"[{profile}]\n")
+        for key in sorted(section.keys()):
+            value = section.get(key)
+            if value is None:
+                continue
+            if not isinstance(value, str):
+                # Force-stringify; the schema is all-strings today.
+                value = str(value)
+            lines.append(f'{key} = "{_escape_toml(value)}"\n')
+        lines.append("\n")
+
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text("".join(lines), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def _escape_toml(value: str) -> str:
+    """Escape the bare-minimum characters that break a basic TOML string."""
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")

robotrace/_http.py

@@ -0,0 +1,203 @@
+"""Internal HTTP wrapper.
+
+Centralizes:
+  • auth header construction
+  • base_url normalization
+  • status-code → exception mapping
+  • redaction of the API key in error messages
+
+Public API is intentionally minimal — call sites use only `request()`,
+`upload_file()`, and the dataclass shapes. Avoids spreading httpx
+specifics through `client.py` / `episode.py`.
+
+NEVER log the value of the `Authorization` header or any request body
+to the ingest endpoint. Both can carry secrets per AGENTS.md.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from . import _version
+from .errors import (
+    APIError,
+    AuthError,
+    ConflictError,
+    NotFoundError,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+
+USER_AGENT = f"robotrace-python/{_version.__version__}"
+
+# Default request timeout. Generous on read because the create call
+# may block briefly on R2 signing; the upload PUT to R2 has its own
+# (longer) timeout in `upload_file`.
+DEFAULT_TIMEOUT = httpx.Timeout(connect=10.0, read=30.0, write=30.0, pool=10.0)
+
+# Object-storage uploads can run minutes for multi-GB videos. We let
+# httpx stream the body so memory stays flat regardless of file size,
+# and bump the read/write timeout accordingly.
+UPLOAD_TIMEOUT = httpx.Timeout(connect=15.0, read=600.0, write=600.0, pool=15.0)
+
+
+class HTTPClient:
+    """Thin wrapper around httpx.Client with RoboTrace defaults."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: httpx.Timeout | float | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._api_key = api_key
+        # Trim trailing slash so we can join paths with a leading slash
+        # without ending up with `//api/...`.
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout if timeout is not None else DEFAULT_TIMEOUT,
+            headers={
+                "User-Agent": USER_AGENT,
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+            },
+            # `transport` is a hook for tests (httpx.MockTransport).
+            # Production callers leave it None and let httpx pick.
+            transport=transport,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ── core request ────────────────────────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Send a JSON request and return the parsed JSON response.
+
+        Maps HTTP errors to the typed exception hierarchy. The raised
+        exception's `response_body` always carries the parsed body
+        (or raw text) so callers can introspect server-supplied
+        details without re-parsing.
+        """
+        try:
+            response = self._client.request(method, path, json=json)
+        except httpx.TimeoutException as exc:
+            raise TransportError(f"timeout calling {path}: {exc}") from exc
+        except httpx.HTTPError as exc:
+            raise TransportError(f"transport error calling {path}: {exc}") from exc
+
+        return self._parse_response(response, path)
+
+    # ── streaming upload to a signed PUT URL ────────────────────────
+
+    def upload_file(
+        self,
+        url: str,
+        path: str | Path,
+        *,
+        content_type: str,
+    ) -> int:
+        """PUT `path` to `url` with `content_type`. Returns bytes uploaded.
+
+        Streams the file from disk so we don't blow up on multi-GB
+        videos. Uses a fresh httpx client (no auth header — the
+        signed URL carries the credentials) and a long timeout.
+        """
+        file_path = Path(path)
+        if not file_path.is_file():
+            raise FileNotFoundError(f"artifact not found: {file_path}")
+        size = file_path.stat().st_size
+
+        try:
+            with file_path.open("rb") as fh, httpx.Client(
+                timeout=UPLOAD_TIMEOUT,
+                # Don't inherit our auth header here — the signed URL
+                # already carries the auth as query params.
+            ) as client:
+                response = client.put(
+                    url,
+                    content=fh,
+                    headers={
+                        "Content-Type": content_type,
+                        "Content-Length": str(size),
+                        "User-Agent": USER_AGENT,
+                    },
+                )
+        except httpx.TimeoutException as exc:
+            raise TransportError(f"upload timeout for {file_path.name}: {exc}") from exc
+        except httpx.HTTPError as exc:
+            raise TransportError(f"upload transport error for {file_path.name}: {exc}") from exc
+
+        if response.status_code >= 400:
+            # Object storage error bodies are XML, not JSON. Surface
+            # the raw text in the exception so the user can debug
+            # bucket / CORS / signature mismatches.
+            raise APIError(
+                f"upload failed for {file_path.name} ({response.status_code})",
+                status_code=response.status_code,
+                response_body=response.text[:1000],
+            )
+        return size
+
+    # ── internals ───────────────────────────────────────────────────
+
+    def _parse_response(self, response: httpx.Response, path: str) -> dict[str, Any]:
+        # Try JSON first; fall back to raw text so 5xx HTML pages
+        # don't crash error reporting.
+        try:
+            body: object = response.json()
+        except ValueError:
+            body = response.text
+
+        if response.is_success:
+            if isinstance(body, dict):
+                return body
+            # The ingest endpoints always return JSON objects; anything
+            # else is a server contract violation.
+            raise ServerError(
+                f"unexpected non-JSON success body from {path}",
+                status_code=response.status_code,
+                response_body=body,
+            )
+
+        message = self._error_message(body, response.status_code)
+        cls = _STATUS_TO_ERROR.get(response.status_code, APIError)
+        # 5xx falls through to ServerError. 401/404/409/4xx route to
+        # their typed subclasses for ergonomic catch blocks.
+        if response.status_code >= 500:
+            cls = ServerError
+        raise cls(message, status_code=response.status_code, response_body=body)
+
+    @staticmethod
+    def _error_message(body: object, status_code: int) -> str:
+        if isinstance(body, dict):
+            err = body.get("error")
+            if isinstance(err, str) and err:
+                return err
+        return f"HTTP {status_code}"
+
+
+_STATUS_TO_ERROR: dict[int, type[APIError]] = {
+    400: ValidationError,
+    401: AuthError,
+    404: NotFoundError,
+    409: ConflictError,
+}