openrunner-sdk 0.1.0__py3-none-any.whl

openrunner/__init__.py

@@ -0,0 +1,273 @@
+"""OpenRunner SDK - W&B-compatible ML experiment tracking.
+
+Public API:
+    openrunner.init(project=..., name=..., config=...)  -> Run
+    openrunner.log({"loss": 0.5}, step=10)              -> None
+    openrunner.finish(exit_code=0)                      -> None
+    openrunner.config       -> Config proxy
+    openrunner.summary      -> Summary proxy
+    openrunner.run          -> active Run or None
+    openrunner.Image        -> Image class for media logging
+    openrunner.Table        -> Table class for structured data
+    openrunner.Artifact     -> Artifact class for versioned file collections
+    openrunner.log_artifact -> Upload an artifact
+    openrunner.use_artifact -> Download an artifact (cached)
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from openrunner.artifact import Artifact
+from openrunner.config import Config
+from openrunner.media import Image, Table
+from openrunner.run import Run
+from openrunner.settings import SDKSettings
+from openrunner.summary import Summary
+
+__version__ = "0.1.0"
+
+logger = logging.getLogger("openrunner")
+
+# Active run state
+_active_run: Run | None = None
+
+
+# ---------------------------------------------------------------------------
+# Proxy objects for module-level config/summary access
+# ---------------------------------------------------------------------------
+
+class _ConfigProxy:
+    """Proxy that delegates attribute access to the active run's Config.
+
+    Since Python modules can't have properties, this proxy object sits
+    at ``openrunner.config`` and forwards all access to ``_active_run.config``.
+    """
+
+    def __getattr__(self, name: str) -> Any:
+        if _active_run is not None:
+            return getattr(_active_run.config, name)
+        raise AttributeError(f"No active run -- call openrunner.init() first")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if _active_run is not None:
+            setattr(_active_run.config, name, value)
+        else:
+            logger.warning("openrunner.config: no active run -- call openrunner.init() first")
+
+    def __getitem__(self, key: str) -> Any:
+        if _active_run is not None:
+            return _active_run.config[key]
+        raise KeyError(f"No active run -- call openrunner.init() first")
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        if _active_run is not None:
+            _active_run.config[key] = value
+        else:
+            logger.warning("openrunner.config: no active run -- call openrunner.init() first")
+
+    def __repr__(self) -> str:
+        if _active_run is not None:
+            return repr(_active_run.config)
+        return "ConfigProxy(no active run)"
+
+
+class _SummaryProxy:
+    """Proxy that delegates attribute access to the active run's Summary."""
+
+    def __getattr__(self, name: str) -> Any:
+        if _active_run is not None:
+            return getattr(_active_run.summary, name)
+        raise AttributeError(f"No active run -- call openrunner.init() first")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if _active_run is not None:
+            setattr(_active_run.summary, name, value)
+        else:
+            logger.warning("openrunner.summary: no active run -- call openrunner.init() first")
+
+    def __getitem__(self, key: str) -> Any:
+        if _active_run is not None:
+            return _active_run.summary[key]
+        raise KeyError(f"No active run -- call openrunner.init() first")
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        if _active_run is not None:
+            _active_run.summary[key] = value
+        else:
+            logger.warning("openrunner.summary: no active run -- call openrunner.init() first")
+
+    def __repr__(self) -> str:
+        if _active_run is not None:
+            return repr(_active_run.summary)
+        return "SummaryProxy(no active run)"
+
+
+# Module-level proxy instances
+config = _ConfigProxy()
+summary = _SummaryProxy()
+
+
+# ---------------------------------------------------------------------------
+# Public API functions
+# ---------------------------------------------------------------------------
+
+def init(
+    project: str | None = None,
+    name: str | None = None,
+    config: dict[str, Any] | None = None,
+    tags: list[str] | None = None,
+    notes: str | None = None,
+    group: str | None = None,
+    job_type: str | None = None,
+    id: str | None = None,
+    resume: bool | str | None = None,
+    **kwargs: Any,
+) -> Run | None:
+    """Initialize a new run.
+
+    Creates a run on the server, starts the background sender thread,
+    and returns the Run object. Never raises -- SDK failures must not
+    crash training code.
+
+    Args:
+        project: Project name (or OPENRUNNER_PROJECT env var, or "uncategorized").
+        name: Display name for the run.
+        config: Hyperparameter dict (sent to server at init time, SDK-12).
+        tags: List of tags for the run.
+        notes: Notes/description for the run.
+        group: Group name for related runs.
+        job_type: Job type label.
+        id: Custom run ID (8-char alphanumeric generated if not provided).
+        resume: Resume mode -- True/"allow" (resume if exists, fresh otherwise)
+                or "must" (error if parent not found). The ``id`` parameter
+                is treated as the parent run ID when resuming.
+
+    Returns:
+        The Run object, or None if initialization fails.
+    """
+    global _active_run
+
+    try:
+        settings = SDKSettings()
+
+        # Resolve project
+        resolved_project = project or settings.project or "uncategorized"
+
+        # Warn if no API key (skip in offline mode)
+        if not settings.api_key and settings.mode != "offline":
+            logger.warning(
+                "No API key set. Set OPENRUNNER_API_KEY or WANDB_API_KEY "
+                "environment variable for server communication."
+            )
+
+        # Create run
+        run = Run(
+            project=resolved_project,
+            name=name,
+            config_dict=config,
+            tags=tags,
+            notes=notes,
+            group=group,
+            job_type=job_type,
+            run_id=id,
+            settings=settings,
+            resume=resume,
+        )
+
+        _active_run = run
+        return run
+
+    except Exception as e:
+        logger.warning("openrunner.init() failed: %s", e)
+        return None
+
+
+def log(
+    data: dict[str, Any],
+    step: int | None = None,
+    commit: bool = True,
+) -> None:
+    """Log metrics. Never raises -- training must not be interrupted.
+
+    Args:
+        data: Dict of metric key-value pairs.
+        step: Explicit step value.
+        commit: If True (default), finalize the current step.
+    """
+    try:
+        if _active_run is None:
+            logger.warning("openrunner.log(): no active run -- call openrunner.init() first")
+            return
+        _active_run.log(data, step=step, commit=commit)
+    except Exception as e:
+        logger.warning("openrunner.log() failed: %s", e)
+
+
+def finish(
+    exit_code: int | None = None,
+    quiet: bool | None = None,
+) -> None:
+    """Finish the active run. Never raises.
+
+    Args:
+        exit_code: Optional exit code.
+        quiet: If True, suppress the finish message.
+    """
+    global _active_run
+
+    try:
+        if _active_run is None:
+            return
+        _active_run.finish(exit_code=exit_code, quiet=quiet or False)
+        _active_run = None
+    except Exception as e:
+        logger.warning("openrunner.finish() failed: %s", e)
+        _active_run = None
+
+
+def log_artifact(artifact: Artifact) -> dict[str, Any] | None:
+    """Upload an artifact to the active run. Never raises.
+
+    Args:
+        artifact: The Artifact object with files added via add_file/add_dir.
+
+    Returns:
+        Server response dict with version info, or None on failure.
+    """
+    try:
+        if _active_run is None:
+            logger.warning("openrunner.log_artifact(): no active run")
+            return None
+        return _active_run.log_artifact(artifact)
+    except Exception as e:
+        logger.warning("openrunner.log_artifact() failed: %s", e)
+        return None
+
+
+def use_artifact(name: str, version: int | None = None) -> Path | None:
+    """Download an artifact and cache locally. Never raises.
+
+    Args:
+        name: Artifact name.
+        version: Specific version number, or None for latest.
+
+    Returns:
+        Path to the local artifact directory, or None on failure.
+    """
+    try:
+        if _active_run is None:
+            logger.warning("openrunner.use_artifact(): no active run")
+            return None
+        return _active_run.use_artifact(name, version)
+    except Exception as e:
+        logger.warning("openrunner.use_artifact() failed: %s", e)
+        return None
+
+
+@property  # type: ignore[misc]
+def run() -> Run | None:
+    """Return the active run, or None."""
+    return _active_run

openrunner/api_client.py

@@ -0,0 +1,368 @@
+"""HTTP client for OpenRunner server communication.
+
+Uses httpx.Client (synchronous, thread-safe) with defensive error handling.
+All methods log warnings on failure and never raise exceptions to the caller.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger("openrunner")
+
+
+class APIClient:
+    """HTTP client for the OpenRunner server API.
+
+    All methods are defensive -- they catch exceptions, log warnings,
+    and return None/0 rather than propagating errors to the caller.
+    This ensures SDK failures never crash training code.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        kwargs: dict[str, Any] = {
+            "base_url": f"{base_url.rstrip('/')}/api/v1",
+            "headers": {"Authorization": f"Bearer {api_key}"},
+            "timeout": 30.0,
+        }
+        if transport is not None:
+            kwargs["transport"] = transport
+
+        self._client = httpx.Client(**kwargs)
+
+    def create_run(self, data: dict[str, Any]) -> dict[str, Any] | None:
+        """POST /runs -- create a new run on the server.
+
+        Returns the response JSON dict, or None on failure.
+        """
+        try:
+            response = self._client.post("/runs", json=data)
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            logger.warning("create_run failed: %s", e)
+            return None
+
+    def update_run(self, run_id: str, data: dict[str, Any]) -> dict[str, Any] | None:
+        """PATCH /runs/{run_id} -- update run state/summary/config.
+
+        Returns the response JSON dict, or None on failure.
+        """
+        try:
+            response = self._client.patch(f"/runs/{run_id}", json=data)
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            logger.warning("update_run failed: %s", e)
+            return None
+
+    def post_metrics(self, run_id: str, metrics: list[dict[str, Any]]) -> int:
+        """POST /runs/{run_id}/metrics -- send a batch of metric records.
+
+        Returns the count of metrics accepted, or 0 on failure.
+        """
+        try:
+            response = self._client.post(
+                f"/runs/{run_id}/metrics",
+                json={"metrics": metrics},
+            )
+            response.raise_for_status()
+            return response.json().get("count", 0)
+        except Exception as e:
+            logger.warning("post_metrics failed: %s", e)
+            return 0
+
+    def get_run(self, run_id: str) -> dict[str, Any] | None:
+        """GET /runs/{run_id} -- fetch run data.
+
+        Returns the response JSON dict, or None on failure/not-found.
+        """
+        try:
+            response = self._client.get(f"/runs/{run_id}")
+            if response.status_code == 404:
+                return None
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            logger.warning("get_run failed: %s", e)
+            return None
+
+    def get_run_max_step(self, run_id: str) -> int:
+        """GET /runs/{run_id}/metrics -- return max step across all metric keys.
+
+        Fetches a small sample of metrics and finds the maximum step value.
+        Returns 0 if no metrics exist or on failure.
+        """
+        try:
+            response = self._client.get(
+                f"/runs/{run_id}/metrics", params={"max_points": 10}
+            )
+            if response.status_code == 404:
+                return 0
+            response.raise_for_status()
+            data = response.json()
+            max_step = 0
+            # data is a dict of metric_key -> list of {step, value, ...}
+            if isinstance(data, dict):
+                for key, series in data.items():
+                    if isinstance(series, list):
+                        for point in series:
+                            step = point.get("step", 0)
+                            if step > max_step:
+                                max_step = step
+            return max_step
+        except Exception as e:
+            logger.warning("get_run_max_step failed: %s", e)
+            return 0
+
+    def sync_metrics(self, run_id: str, metrics: list[dict[str, Any]]) -> int:
+        """POST /runs/{run_id}/sync-metrics -- idempotent metric sync.
+
+        Calls the sync-metrics endpoint which uses ON CONFLICT DO NOTHING
+        to handle duplicate metric points. Returns count or 0 on failure.
+        """
+        try:
+            response = self._client.post(
+                f"/runs/{run_id}/sync-metrics",
+                json={"metrics": metrics},
+            )
+            response.raise_for_status()
+            return response.json().get("count", 0)
+        except Exception as e:
+            logger.warning("sync_metrics failed: %s", e)
+            return 0
+
+    def post_heartbeat(self, run_id: str) -> None:
+        """POST /runs/{run_id}/heartbeat -- send a heartbeat signal.
+
+        Logs a warning on failure but never raises.
+        """
+        try:
+            response = self._client.post(f"/runs/{run_id}/heartbeat")
+            response.raise_for_status()
+        except Exception as e:
+            logger.warning("post_heartbeat failed: %s", e)
+
+    # -- Listing methods -------------------------------------------------------
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        """GET /projects -- list all projects the user has access to.
+
+        Returns a list of project dicts, or empty list on failure.
+        """
+        try:
+            response = self._client.get("/projects")
+            response.raise_for_status()
+            data = response.json()
+            # Server may return {projects: [...]} or [...]
+            if isinstance(data, list):
+                return data
+            return data.get("projects", data.get("items", []))
+        except Exception as e:
+            logger.warning("list_projects failed: %s", e)
+            return []
+
+    def list_runs(self, project_id: str) -> list[dict[str, Any]]:
+        """GET /projects/{project_id}/runs -- list runs in a project.
+
+        Returns a list of run dicts, or empty list on failure.
+        """
+        try:
+            response = self._client.get(f"/projects/{project_id}/runs")
+            response.raise_for_status()
+            data = response.json()
+            if isinstance(data, list):
+                return data
+            return data.get("runs", data.get("items", []))
+        except Exception as e:
+            logger.warning("list_runs failed: %s", e)
+            return []
+
+    # -- Artifact methods ------------------------------------------------------
+
+    def create_artifact_version(
+        self,
+        run_id: str,
+        name: str,
+        type: str,
+        files: list[dict[str, Any]],
+        description: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
+        """POST /runs/{run_id}/artifacts -- create a new artifact version.
+
+        Returns {version_id, version, upload_urls}, or None on failure.
+        """
+        try:
+            body: dict[str, Any] = {
+                "name": name,
+                "type": type,
+                "files": files,
+            }
+            if description is not None:
+                body["description"] = description
+            if metadata is not None:
+                body["metadata"] = metadata
+            response = self._client.post(f"/runs/{run_id}/artifacts", json=body)
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            logger.warning("create_artifact_version failed: %s", e)
+            return None
+
+    def confirm_artifact_version(
+        self, version_id: str
+    ) -> dict[str, Any] | None:
+        """POST /artifacts/versions/{version_id}/confirm -- confirm upload.
+
+        Returns {status, version}, or None on failure.
+        """
+        try:
+            response = self._client.post(
+                f"/artifacts/versions/{version_id}/confirm"
+            )
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            logger.warning("confirm_artifact_version failed: %s", e)
+            return None
+
+    def use_artifact(
+        self,
+        run_id: str,
+        artifact_name: str,
+        version: int | None = None,
+    ) -> dict[str, Any] | None:
+        """POST /runs/{run_id}/use-artifact -- get download URLs.
+
+        Returns download info dict, or None on failure.
+        """
+        try:
+            body: dict[str, Any] = {"artifact_name": artifact_name}
+            if version is not None:
+                body["version"] = version
+            response = self._client.post(
+                f"/runs/{run_id}/use-artifact", json=body
+            )
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            logger.warning("use_artifact failed: %s", e)
+            return None
+
+    def upload_file_to_presigned_url(
+        self, presigned_url: str, file_path: str
+    ) -> bool:
+        """PUT raw file bytes to a presigned URL.
+
+        Uses httpx directly (not self._client) because presigned URLs
+        are absolute and should not have a base_url prefix.
+        """
+        try:
+            with open(file_path, "rb") as f:
+                data = f.read()
+            resp = httpx.put(presigned_url, content=data, timeout=300.0)
+            resp.raise_for_status()
+            return True
+        except Exception as e:
+            logger.warning("upload_file_to_presigned_url failed: %s", e)
+            return False
+
+    def download_file_from_presigned_url(
+        self, presigned_url: str
+    ) -> bytes | None:
+        """GET file bytes from a presigned URL.
+
+        Uses httpx directly (not self._client) because presigned URLs
+        are absolute and should not have a base_url prefix.
+        """
+        try:
+            resp = httpx.get(presigned_url, timeout=300.0)
+            resp.raise_for_status()
+            return resp.content
+        except Exception as e:
+            logger.warning("download_file_from_presigned_url failed: %s", e)
+            return None
+
+    # -- Media methods -------------------------------------------------------
+
+    def create_media_file(
+        self,
+        run_id: str,
+        key: str,
+        media_type: str,
+        step: int | None = None,
+        caption: str | None = None,
+        content_type: str | None = None,
+        width: int | None = None,
+        height: int | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
+        """POST /runs/{run_id}/media -- create a media file record.
+
+        Returns {id, storage_key, presigned_url}, or None on failure.
+        """
+        try:
+            body: dict[str, Any] = {
+                "key": key,
+                "media_type": media_type,
+            }
+            if step is not None:
+                body["step"] = step
+            if caption is not None:
+                body["caption"] = caption
+            if content_type is not None:
+                body["content_type"] = content_type
+            if width is not None:
+                body["width"] = width
+            if height is not None:
+                body["height"] = height
+            if data is not None:
+                body["data"] = data
+            response = self._client.post(f"/runs/{run_id}/media", json=body)
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            logger.warning("create_media_file failed: %s", e)
+            return None
+
+    def upload_media_bytes(
+        self,
+        presigned_url: str,
+        data_bytes: bytes,
+        content_type: str = "image/png",
+    ) -> bool:
+        """PUT bytes to a presigned URL with Content-Type header.
+
+        Uses httpx directly (not self._client) because presigned URLs
+        are absolute and should not have a base_url prefix.
+        """
+        try:
+            resp = httpx.put(
+                presigned_url,
+                content=data_bytes,
+                headers={"Content-Type": content_type},
+                timeout=300.0,
+            )
+            resp.raise_for_status()
+            return True
+        except Exception as e:
+            logger.warning("upload_media_bytes failed: %s", e)
+            return False
+
+    # -- Lifecycle -----------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying httpx client."""
+        try:
+            self._client.close()
+        except Exception:
+            pass