openrelay-sdk 0.1.0__py3-none-any.whl

openrelay/__init__.py

@@ -0,0 +1,54 @@
+"""OpenRelay Python SDK."""
+
+from ._client import AsyncClient, Client
+from ._exceptions import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    InternalServerError,
+    InvalidRequestError,
+    NotFoundError,
+    OpenRelayError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+from ._version import __version__
+from .types.gpus import (
+    GpuAvailability,
+    GpuAvailabilityRegion,
+    GpuModel,
+    GpuModelAvailability,
+    GpuPricing,
+    GpuPricingTier,
+)
+from .types.vms import Vm, VmActionResponse, VmCreateResponse
+
+__all__ = [
+    "__version__",
+    # Clients
+    "Client",
+    "AsyncClient",
+    # Exceptions
+    "OpenRelayError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "InvalidRequestError",
+    "RateLimitError",
+    "InternalServerError",
+    "APIConnectionError",
+    "APITimeoutError",
+    # GPU types
+    "GpuModel",
+    "GpuModelAvailability",
+    "GpuAvailability",
+    "GpuAvailabilityRegion",
+    "GpuPricing",
+    "GpuPricingTier",
+    # VM types
+    "Vm",
+    "VmCreateResponse",
+    "VmActionResponse",
+]

openrelay/_base_client.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import os
+import random
+import re
+from typing import Any, Dict, List, Optional, Tuple, Type, TypeVar
+
+import httpx
+from pydantic import BaseModel
+
+from ._constants import (
+    API_KEY_ENV_VAR,
+    CAPACITY_CODES,
+    BASE_URL_ENV_VAR,
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    INITIAL_RETRY_DELAY,
+    MAX_RETRY_DELAY,
+)
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    InternalServerError,
+    InvalidRequestError,
+    NotFoundError,
+    OpenRelayError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+from ._version import __version__
+
+T = TypeVar("T", bound=BaseModel)
+
+_UUID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE
+)
+
+_ERROR_TYPE_MAP: Dict[str, Type[APIError]] = {
+    "authentication_error": AuthenticationError,
+    "permission_error": PermissionDeniedError,
+    "not_found_error": NotFoundError,
+    "invalid_request_error": InvalidRequestError,
+    "rate_limit_error": RateLimitError,
+    "server_error": InternalServerError,
+}
+
+
+def _is_uuid(value: str) -> bool:
+    return bool(_UUID_RE.match(value))
+
+
+# The error type a flat control-plane body implies, which carries no type field.
+_STATUS_ERROR_TYPE: Dict[int, str] = {
+    400: "invalid_request_error",
+    401: "authentication_error",
+    403: "permission_error",
+    404: "not_found_error",
+    429: "rate_limit_error",
+}
+
+
+def _parse_error(response: httpx.Response) -> Tuple[str, str, Optional[str]]:
+    """(type, message, code) from an error response. The control plane writes a
+    flat {"error": "<message>", "code": "<CODE>"}, which carries no type, so the
+    type follows from the status. The nested {"error": {"type", "message",
+    "code"}} shape is read as it comes. A body that is neither yields a
+    server_error with a status-only message and no code."""
+    try:
+        body = response.json()
+    except Exception:
+        body = None
+    if isinstance(body, dict):
+        error = body.get("error", {})
+        if isinstance(error, str):
+            status = response.status_code
+            code = body.get("code")
+            return (
+                "server_error" if status >= 500 else _STATUS_ERROR_TYPE.get(status, "api_error"),
+                error,
+                code if isinstance(code, str) else None,
+            )
+        if isinstance(error, dict):
+            code = error.get("code")
+            return (
+                error.get("type", "server_error"),
+                error.get("message", "Unknown error"),
+                code if isinstance(code, str) else None,
+            )
+    return "server_error", f"HTTP {response.status_code}", None
+
+
+class BaseClient:
+    """Shared configuration for sync and async clients."""
+
+    _gpu_name_cache: Optional[Dict[str, str]]
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> None:
+        self.api_key = api_key or os.environ.get(API_KEY_ENV_VAR)
+        if not self.api_key:
+            raise OpenRelayError(
+                f"API key is required. Pass api_key= or set {API_KEY_ENV_VAR}."
+            )
+        self.base_url = (
+            base_url or os.environ.get(BASE_URL_ENV_VAR) or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout if timeout is not None else DEFAULT_TIMEOUT
+        self.max_retries = (
+            max_retries if max_retries is not None else DEFAULT_MAX_RETRIES
+        )
+        self._gpu_name_cache = None
+
+    def _build_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": f"openrelay-python/{__version__}",
+        }
+
+    def _build_url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    def _should_retry(self, response: httpx.Response) -> bool:
+        if response.status_code == 503 and _parse_error(response)[2] in CAPACITY_CODES:
+            return False
+        return response.status_code in (429, 500, 502, 503, 504)
+
+    def _retry_delay(
+        self, attempt: int, response_headers: Optional[Dict[str, str]] = None
+    ) -> float:
+        if response_headers:
+            retry_after = response_headers.get("retry-after")
+            if retry_after:
+                try:
+                    return float(retry_after)
+                except (ValueError, TypeError):
+                    pass
+        delay = min(INITIAL_RETRY_DELAY * (2**attempt), MAX_RETRY_DELAY)
+        jitter = random.random() * 0.5 * delay
+        return delay + jitter
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.is_success:
+            return
+
+        error_type, message, code = _parse_error(response)
+        exc_class = _ERROR_TYPE_MAP.get(error_type, APIError)
+        raise exc_class(
+            message,
+            status_code=response.status_code,
+            type=error_type,
+            code=code,
+            headers=dict(response.headers),
+        )
+
+    def _parse_response(self, response: httpx.Response, model: Type[T]) -> T:
+        body = response.json()
+        data = body.get("data", body)
+        return model.model_validate(data)
+
+    def _parse_response_list(
+        self, response: httpx.Response, model: Type[T]
+    ) -> List[T]:
+        body = response.json()
+        data = body.get("data", [])
+        return [model.model_validate(item) for item in data]

openrelay/_client.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+import httpx
+
+from ._base_client import BaseClient
+from ._exceptions import APIConnectionError, APITimeoutError
+
+
+class Client(BaseClient):
+    """Synchronous OpenRelay API client."""
+
+    def __init__(self, **kwargs: object) -> None:
+        super().__init__(**kwargs)  # type: ignore[arg-type]
+        self._http = httpx.Client(
+            headers=self._build_headers(),
+            timeout=self.timeout,
+        )
+
+        from .resources.gpus import SyncGpus
+        from .resources.vms import SyncVms
+
+        self.gpus = SyncGpus(self)
+        self.vms = SyncVms(self)
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[dict] = None,
+        params: Optional[dict] = None,
+    ) -> httpx.Response:
+        url = self._build_url(path)
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._http.request(
+                    method, url, json=json, params=params
+                )
+            except httpx.TimeoutException as e:
+                last_exc = APITimeoutError(f"Request timed out: {e}")
+                if attempt < self.max_retries:
+                    time.sleep(self._retry_delay(attempt))
+                    continue
+                raise last_exc from e
+            except httpx.HTTPError as e:
+                last_exc = APIConnectionError(
+                    f"Connection error: {e}", cause=e
+                )
+                if attempt < self.max_retries:
+                    time.sleep(self._retry_delay(attempt))
+                    continue
+                raise last_exc from e
+
+            if (
+                self._should_retry(response)
+                and attempt < self.max_retries
+            ):
+                time.sleep(
+                    self._retry_delay(attempt, dict(response.headers))
+                )
+                continue
+
+            self._raise_for_status(response)
+            return response
+
+        raise last_exc or APIConnectionError("Request failed after retries")
+
+    def _resolve_gpu_name(self, gpu_type: str) -> str:
+        """Resolve a friendly GPU name to its UUID, fetching models if needed."""
+        from ._base_client import _is_uuid
+
+        if _is_uuid(gpu_type):
+            return gpu_type
+
+        if self._gpu_name_cache is None:
+            self._refresh_gpu_cache()
+
+        assert self._gpu_name_cache is not None
+        gpu_id = self._gpu_name_cache.get(gpu_type.lower())
+        if gpu_id is None:
+            # Refresh cache once in case new models were added
+            self._refresh_gpu_cache()
+            gpu_id = self._gpu_name_cache.get(gpu_type.lower())
+
+        if gpu_id is None:
+            from ._exceptions import InvalidRequestError
+
+            raise InvalidRequestError(
+                f"Unknown GPU type: '{gpu_type}'. Use client.gpus.list() to see available models.",
+                status_code=400,
+                type="invalid_request_error",
+                code="UNKNOWN_GPU_TYPE",
+            )
+        return gpu_id
+
+    def _refresh_gpu_cache(self) -> None:
+        from .types.gpus import GpuModel
+
+        response = self.request("GET", "/v1/gpus/models")
+        models = self._parse_response_list(response, GpuModel)
+        self._gpu_name_cache = {}
+        for m in models:
+            self._gpu_name_cache[m.name.lower()] = m.id
+            # Also add common short names (e.g., "a100" for "A100 80GB")
+            short = m.name.split()[0].lower()
+            if short not in self._gpu_name_cache:
+                self._gpu_name_cache[short] = m.id
+
+
+class AsyncClient(BaseClient):
+    """Asynchronous OpenRelay API client."""
+
+    def __init__(self, **kwargs: object) -> None:
+        super().__init__(**kwargs)  # type: ignore[arg-type]
+        self._http = httpx.AsyncClient(
+            headers=self._build_headers(),
+            timeout=self.timeout,
+        )
+
+        from .resources.gpus import AsyncGpus
+        from .resources.vms import AsyncVms
+
+        self.gpus = AsyncGpus(self)
+        self.vms = AsyncVms(self)
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[dict] = None,
+        params: Optional[dict] = None,
+    ) -> httpx.Response:
+        import asyncio
+
+        url = self._build_url(path)
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._http.request(
+                    method, url, json=json, params=params
+                )
+            except httpx.TimeoutException as e:
+                last_exc = APITimeoutError(f"Request timed out: {e}")
+                if attempt < self.max_retries:
+                    await asyncio.sleep(self._retry_delay(attempt))
+                    continue
+                raise last_exc from e
+            except httpx.HTTPError as e:
+                last_exc = APIConnectionError(
+                    f"Connection error: {e}", cause=e
+                )
+                if attempt < self.max_retries:
+                    await asyncio.sleep(self._retry_delay(attempt))
+                    continue
+                raise last_exc from e
+
+            if (
+                self._should_retry(response)
+                and attempt < self.max_retries
+            ):
+                await asyncio.sleep(
+                    self._retry_delay(attempt, dict(response.headers))
+                )
+                continue
+
+            self._raise_for_status(response)
+            return response
+
+        raise last_exc or APIConnectionError("Request failed after retries")
+
+    async def _resolve_gpu_name(self, gpu_type: str) -> str:
+        """Resolve a friendly GPU name to its UUID, fetching models if needed."""
+        from ._base_client import _is_uuid
+
+        if _is_uuid(gpu_type):
+            return gpu_type
+
+        if self._gpu_name_cache is None:
+            await self._refresh_gpu_cache()
+
+        assert self._gpu_name_cache is not None
+        gpu_id = self._gpu_name_cache.get(gpu_type.lower())
+        if gpu_id is None:
+            await self._refresh_gpu_cache()
+            gpu_id = self._gpu_name_cache.get(gpu_type.lower())
+
+        if gpu_id is None:
+            from ._exceptions import InvalidRequestError
+
+            raise InvalidRequestError(
+                f"Unknown GPU type: '{gpu_type}'. Use client.gpus.list() to see available models.",
+                status_code=400,
+                type="invalid_request_error",
+                code="UNKNOWN_GPU_TYPE",
+            )
+        return gpu_id
+
+    async def _refresh_gpu_cache(self) -> None:
+        from .types.gpus import GpuModel
+
+        response = await self.request("GET", "/v1/gpus/models")
+        models = self._parse_response_list(response, GpuModel)
+        self._gpu_name_cache = {}
+        for m in models:
+            self._gpu_name_cache[m.name.lower()] = m.id
+            short = m.name.split()[0].lower()
+            if short not in self._gpu_name_cache:
+                self._gpu_name_cache[short] = m.id

openrelay/_constants.py

@@ -0,0 +1,25 @@
+DEFAULT_BASE_URL = "https://api.openrelay.inc"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+INITIAL_RETRY_DELAY = 0.5
+MAX_RETRY_DELAY = 8.0
+
+# The variable names the `orl` CLI reads, so one shell setup serves both.
+API_KEY_ENV_VAR = "OPENRELAY_API_KEY"
+BASE_URL_ENV_VAR = "OPENRELAY_API_URL"
+
+# The control plane's capacity refusal codes (capacityCodes in
+# services/control-plane-go/capacity_refusal.go). A 503 carrying one means there
+# is no capacity for the request right now; the same request does not make room,
+# so the client returns it to the caller instead of retrying.
+CAPACITY_CODES = frozenset(
+    {
+        "NODE_AT_CAPACITY",
+        "INSUFFICIENT_GPU_CAPACITY",
+        "INSUFFICIENT_CPU_CAPACITY",
+        "INSUFFICIENT_HOST_CAPACITY",
+        "INSUFFICIENT_IP_CAPACITY",
+        "VM_NODE_BUSY",
+        "POD_NODE_BUSY",
+    }
+)

openrelay/_exceptions.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+
+class OpenRelayError(Exception):
+    """Base exception for all OpenRelay SDK errors."""
+
+
+class APIError(OpenRelayError):
+    """Error returned by the OpenRelay API."""
+
+    status_code: int
+    type: str
+    code: Optional[str]
+    headers: Dict[str, str]
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        type: str,
+        code: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.type = type
+        self.code = code
+        self.headers = headers or {}
+
+
+class AuthenticationError(APIError):
+    """401 - Invalid, expired, or revoked API key."""
+
+
+class PermissionDeniedError(APIError):
+    """403 - Insufficient permissions or balance."""
+
+
+class NotFoundError(APIError):
+    """404 - Resource not found."""
+
+
+class InvalidRequestError(APIError):
+    """400 - Validation or bad request error."""
+
+
+class RateLimitError(APIError):
+    """429 - Rate limit exceeded."""
+
+
+class InternalServerError(APIError):
+    """500+ - Server-side error."""
+
+
+class APIConnectionError(OpenRelayError):
+    """Network connectivity error."""
+
+    def __init__(
+        self, message: str = "Connection error", *, cause: Optional[Exception] = None
+    ) -> None:
+        super().__init__(message)
+        self.__cause__ = cause
+
+
+class APITimeoutError(APIConnectionError):
+    """Request timed out."""
+
+    def __init__(self, message: str = "Request timed out") -> None:
+        super().__init__(message)

openrelay/_types.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from typing import Literal
+
+Tier = Literal["community", "verified"]
+ResourceSize = Literal["small", "medium", "large", "xl"]
+VmStatus = Literal[
+    "pending", "deploying", "running", "stopped", "failed", "terminated"
+]

openrelay/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

openrelay/resources/__init__.py

@@ -0,0 +1,9 @@
+from .gpus import AsyncGpus, SyncGpus
+from .vms import AsyncVms, SyncVms
+
+__all__ = [
+    "SyncGpus",
+    "AsyncGpus",
+    "SyncVms",
+    "AsyncVms",
+]

openrelay/resources/gpus.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Optional
+
+from .._types import Tier
+from ..types.gpus import GpuAvailability, GpuModel, GpuPricing
+
+if TYPE_CHECKING:
+    from .._client import AsyncClient, Client
+
+
+def _build_models_params(
+    tier: Optional[Tier] = None,
+    regions: Optional[List[str]] = None,
+) -> Optional[dict]:
+    params: dict = {}
+    if tier:
+        params["tier"] = tier
+    if regions:
+        params["regions"] = ",".join(regions)
+    return params or None
+
+
+def _build_availability_params(
+    tier: Optional[Tier] = None,
+    region: Optional[str] = None,
+) -> Optional[dict]:
+    params: dict = {}
+    if tier:
+        params["tier"] = tier
+    if region:
+        params["region"] = region
+    return params or None
+
+
+class SyncGpus:
+    """Synchronous GPU operations."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        tier: Optional[Tier] = None,
+        regions: Optional[List[str]] = None,
+    ) -> List[GpuModel]:
+        """List available GPU models."""
+        params = _build_models_params(tier, regions)
+        response = self._client.request("GET", "/v1/gpus/models", params=params)
+        return self._client._parse_response_list(response, GpuModel)
+
+    def availability(
+        self,
+        gpu_type: Optional[str] = None,
+        *,
+        tier: Optional[Tier] = None,
+        region: Optional[str] = None,
+    ) -> GpuAvailability:
+        """Check GPU availability by region."""
+        params = _build_availability_params(tier, region)
+        response = self._client.request(
+            "GET", "/v1/gpus/availability", params=params
+        )
+        return self._client._parse_response(response, GpuAvailability)
+
+    def pricing(self) -> List[GpuPricing]:
+        """Get GPU pricing."""
+        response = self._client.request("GET", "/v1/gpus/pricing")
+        return self._client._parse_response_list(response, GpuPricing)
+
+
+class AsyncGpus:
+    """Asynchronous GPU operations."""
+
+    def __init__(self, client: AsyncClient) -> None:
+        self._client = client
+
+    async def list(
+        self,
+        *,
+        tier: Optional[Tier] = None,
+        regions: Optional[List[str]] = None,
+    ) -> List[GpuModel]:
+        """List available GPU models."""
+        params = _build_models_params(tier, regions)
+        response = await self._client.request(
+            "GET", "/v1/gpus/models", params=params
+        )
+        return self._client._parse_response_list(response, GpuModel)
+
+    async def availability(
+        self,
+        gpu_type: Optional[str] = None,
+        *,
+        tier: Optional[Tier] = None,
+        region: Optional[str] = None,
+    ) -> GpuAvailability:
+        """Check GPU availability by region."""
+        params = _build_availability_params(tier, region)
+        response = await self._client.request(
+            "GET", "/v1/gpus/availability", params=params
+        )
+        return self._client._parse_response(response, GpuAvailability)
+
+    async def pricing(self) -> List[GpuPricing]:
+        """Get GPU pricing."""
+        response = await self._client.request("GET", "/v1/gpus/pricing")
+        return self._client._parse_response_list(response, GpuPricing)

openrelay/resources/vms.py

@@ -0,0 +1,352 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Dict, List, Optional
+
+from .._exceptions import OpenRelayError
+from .._types import ResourceSize, Tier
+from ..types.vms import Vm, VmActionResponse, VmCreateResponse
+
+if TYPE_CHECKING:
+    from .._client import AsyncClient, Client
+
+_TERMINAL_STATUSES = {"running", "failed", "stopped", "terminated"}
+
+
+def _build_create_body(
+    *,
+    name: str,
+    tier: Tier = "community",
+    # Friendly aliases
+    gpu_type: Optional[str] = None,
+    container: Optional[str] = None,
+    env: Optional[Dict[str, str]] = None,
+    # Direct API parameter names
+    gpu_model_id: Optional[str] = None,
+    gpu_count: int = 0,
+    resource_size: ResourceSize = "large",
+    guest_mem_mb: Optional[int] = None,
+    preferred_regions: Optional[List[str]] = None,
+    allow_fallback: bool = False,
+    image_url: Optional[str] = None,
+    container_port: Optional[int] = None,
+    container_command: Optional[List[str]] = None,
+    env_vars: Optional[Dict[str, str]] = None,
+    health_checks: Optional[List[str]] = None,
+    health_check_path: str = "/health",
+    health_check_port: Optional[int] = None,
+    disk_size_gb: Optional[int] = None,
+    privileged: bool = False,
+    kernel_modules: Optional[List[str]] = None,
+    cloud_init_runcmd: Optional[List[str]] = None,
+    template_id: Optional[str] = None,
+    ssh_key_ids: Optional[List[str]] = None,
+) -> dict:
+    """Build the VM creation request body."""
+    body: dict = {
+        "name": name,
+        "tier": tier,
+        "gpuCount": gpu_count,
+        "allowFallback": allow_fallback,
+        "healthChecks": health_checks or [],
+        "healthCheckPath": health_check_path,
+        "privileged": privileged,
+    }
+
+    # resourceSize is the CPU-only VM tier picker and the API rejects it alongside
+    # a GPU count, so a GPU create omits it (any value passed for one is dropped
+    # rather than turned into a 400). It keeps its "large" default for CPU VMs:
+    # the API resolves an omitted size to "small", so sending nothing would
+    # quietly hand every existing caller a 2 vCPU / 4 GiB guest instead of the
+    # 8 / 16 they have been getting. A GPU VM is sized by guest_mem_mb and
+    # disk_size_gb instead, and omitting both asks the API to size it.
+    if gpu_count <= 0:
+        body["resourceSize"] = resource_size
+    if guest_mem_mb is not None:
+        body["guestMemMb"] = guest_mem_mb
+    if disk_size_gb is not None:
+        body["diskSizeGb"] = disk_size_gb
+
+    if ssh_key_ids:
+        body["sshKeyIds"] = ssh_key_ids
+
+    resolved_gpu = gpu_model_id or gpu_type
+    if resolved_gpu:
+        body["gpuModelId"] = resolved_gpu
+
+    resolved_image = image_url or container
+    if resolved_image:
+        body["imageUrl"] = resolved_image
+
+    resolved_env = env_vars or env
+    if resolved_env:
+        body["envVars"] = resolved_env
+
+    if preferred_regions:
+        body["preferredRegions"] = preferred_regions
+    if container_port is not None:
+        body["containerPort"] = container_port
+    if container_command:
+        body["containerCommand"] = container_command
+    if health_check_port is not None:
+        body["healthCheckPort"] = health_check_port
+    if kernel_modules:
+        body["kernelModules"] = kernel_modules
+    if cloud_init_runcmd:
+        body["cloudInitRuncmd"] = cloud_init_runcmd
+    if template_id:
+        body["templateId"] = template_id
+
+    return body
+
+
+class SyncVms:
+    """Synchronous VM operations."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def get(self, vm_id: str) -> Vm:
+        """Get VM details."""
+        response = self._client.request("GET", f"/api/v1/vms/{vm_id}")
+        return self._client._parse_response(response, Vm)
+
+    def create(
+        self,
+        *,
+        name: str,
+        ssh_key_ids: List[str],
+        tier: Tier = "community",
+        gpu_type: Optional[str] = None,
+        container: Optional[str] = None,
+        env: Optional[Dict[str, str]] = None,
+        gpu_model_id: Optional[str] = None,
+        gpu_count: int = 0,
+        resource_size: ResourceSize = "large",
+        guest_mem_mb: Optional[int] = None,
+        preferred_regions: Optional[List[str]] = None,
+        allow_fallback: bool = False,
+        image_url: Optional[str] = None,
+        container_port: Optional[int] = None,
+        container_command: Optional[List[str]] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        health_checks: Optional[List[str]] = None,
+        health_check_path: str = "/health",
+        health_check_port: Optional[int] = None,
+        disk_size_gb: Optional[int] = None,
+        privileged: bool = False,
+        kernel_modules: Optional[List[str]] = None,
+        cloud_init_runcmd: Optional[List[str]] = None,
+        template_id: Optional[str] = None,
+    ) -> VmCreateResponse:
+        """Create a new VM."""
+        resolved_gpu = gpu_model_id or gpu_type
+        if resolved_gpu:
+            resolved_gpu = self._client._resolve_gpu_name(resolved_gpu)
+
+        body = _build_create_body(
+            name=name,
+            tier=tier,
+            gpu_model_id=resolved_gpu,
+            gpu_count=gpu_count,
+            resource_size=resource_size,
+            guest_mem_mb=guest_mem_mb,
+            preferred_regions=preferred_regions,
+            allow_fallback=allow_fallback,
+            container=container,
+            image_url=image_url,
+            container_port=container_port,
+            container_command=container_command,
+            env=env,
+            env_vars=env_vars,
+            health_checks=health_checks,
+            health_check_path=health_check_path,
+            health_check_port=health_check_port,
+            disk_size_gb=disk_size_gb,
+            privileged=privileged,
+            kernel_modules=kernel_modules,
+            cloud_init_runcmd=cloud_init_runcmd,
+            template_id=template_id,
+            ssh_key_ids=ssh_key_ids,
+        )
+        response = self._client.request("POST", "/api/v1/vms", json=body)
+        return self._client._parse_response(response, VmCreateResponse)
+
+    def delete(self, vm_id: str) -> None:
+        """Terminate a VM."""
+        self._client.request("DELETE", f"/api/v1/vms/{vm_id}")
+
+    def stop(self, vm_id: str) -> VmActionResponse:
+        """Stop a running VM."""
+        response = self._client.request(
+            "POST", f"/api/v1/vms/{vm_id}/stop"
+        )
+        return self._client._parse_response(response, VmActionResponse)
+
+    def restart(self, vm_id: str) -> VmActionResponse:
+        """Restart a stopped VM."""
+        response = self._client.request(
+            "POST", f"/api/v1/vms/{vm_id}/restart"
+        )
+        return self._client._parse_response(response, VmActionResponse)
+
+    def reboot(self, vm_id: str) -> VmActionResponse:
+        """Gracefully reboot a running VM."""
+        response = self._client.request(
+            "POST", f"/api/v1/vms/{vm_id}/reboot"
+        )
+        return self._client._parse_response(response, VmActionResponse)
+
+    def wait_for_status(
+        self,
+        vm_id: str,
+        *,
+        target: str = "running",
+        timeout: float = 600,
+        poll_interval: float = 5.0,
+    ) -> Vm:
+        """Poll until VM reaches target status or a terminal state."""
+        start = time.monotonic()
+        while True:
+            vm = self.get(vm_id)
+            if vm.status == target:
+                return vm
+            if vm.status in _TERMINAL_STATUSES and vm.status != target:
+                raise OpenRelayError(
+                    f"VM reached terminal status '{vm.status}' "
+                    f"instead of '{target}'"
+                )
+            elapsed = time.monotonic() - start
+            if elapsed >= timeout:
+                raise OpenRelayError(
+                    f"Timed out waiting for VM to reach '{target}' "
+                    f"(current: '{vm.status}')"
+                )
+            time.sleep(poll_interval)
+
+
+class AsyncVms:
+    """Asynchronous VM operations."""
+
+    def __init__(self, client: AsyncClient) -> None:
+        self._client = client
+
+    async def get(self, vm_id: str) -> Vm:
+        """Get VM details."""
+        response = await self._client.request("GET", f"/api/v1/vms/{vm_id}")
+        return self._client._parse_response(response, Vm)
+
+    async def create(
+        self,
+        *,
+        name: str,
+        ssh_key_ids: List[str],
+        tier: Tier = "community",
+        gpu_type: Optional[str] = None,
+        container: Optional[str] = None,
+        env: Optional[Dict[str, str]] = None,
+        gpu_model_id: Optional[str] = None,
+        gpu_count: int = 0,
+        resource_size: ResourceSize = "large",
+        guest_mem_mb: Optional[int] = None,
+        preferred_regions: Optional[List[str]] = None,
+        allow_fallback: bool = False,
+        image_url: Optional[str] = None,
+        container_port: Optional[int] = None,
+        container_command: Optional[List[str]] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        health_checks: Optional[List[str]] = None,
+        health_check_path: str = "/health",
+        health_check_port: Optional[int] = None,
+        disk_size_gb: Optional[int] = None,
+        privileged: bool = False,
+        kernel_modules: Optional[List[str]] = None,
+        cloud_init_runcmd: Optional[List[str]] = None,
+        template_id: Optional[str] = None,
+    ) -> VmCreateResponse:
+        """Create a new VM."""
+        resolved_gpu = gpu_model_id or gpu_type
+        if resolved_gpu:
+            resolved_gpu = await self._client._resolve_gpu_name(resolved_gpu)
+
+        body = _build_create_body(
+            name=name,
+            tier=tier,
+            gpu_model_id=resolved_gpu,
+            gpu_count=gpu_count,
+            resource_size=resource_size,
+            guest_mem_mb=guest_mem_mb,
+            preferred_regions=preferred_regions,
+            allow_fallback=allow_fallback,
+            container=container,
+            image_url=image_url,
+            container_port=container_port,
+            container_command=container_command,
+            env=env,
+            env_vars=env_vars,
+            health_checks=health_checks,
+            health_check_path=health_check_path,
+            health_check_port=health_check_port,
+            disk_size_gb=disk_size_gb,
+            privileged=privileged,
+            kernel_modules=kernel_modules,
+            cloud_init_runcmd=cloud_init_runcmd,
+            template_id=template_id,
+            ssh_key_ids=ssh_key_ids,
+        )
+        response = await self._client.request("POST", "/api/v1/vms", json=body)
+        return self._client._parse_response(response, VmCreateResponse)
+
+    async def delete(self, vm_id: str) -> None:
+        """Terminate a VM."""
+        await self._client.request("DELETE", f"/api/v1/vms/{vm_id}")
+
+    async def stop(self, vm_id: str) -> VmActionResponse:
+        """Stop a running VM."""
+        response = await self._client.request(
+            "POST", f"/api/v1/vms/{vm_id}/stop"
+        )
+        return self._client._parse_response(response, VmActionResponse)
+
+    async def restart(self, vm_id: str) -> VmActionResponse:
+        """Restart a stopped VM."""
+        response = await self._client.request(
+            "POST", f"/api/v1/vms/{vm_id}/restart"
+        )
+        return self._client._parse_response(response, VmActionResponse)
+
+    async def reboot(self, vm_id: str) -> VmActionResponse:
+        """Gracefully reboot a running VM."""
+        response = await self._client.request(
+            "POST", f"/api/v1/vms/{vm_id}/reboot"
+        )
+        return self._client._parse_response(response, VmActionResponse)
+
+    async def wait_for_status(
+        self,
+        vm_id: str,
+        *,
+        target: str = "running",
+        timeout: float = 600,
+        poll_interval: float = 5.0,
+    ) -> Vm:
+        """Poll until VM reaches target status or a terminal state."""
+        import asyncio
+
+        start = time.monotonic()
+        while True:
+            vm = await self.get(vm_id)
+            if vm.status == target:
+                return vm
+            if vm.status in _TERMINAL_STATUSES and vm.status != target:
+                raise OpenRelayError(
+                    f"VM reached terminal status '{vm.status}' "
+                    f"instead of '{target}'"
+                )
+            elapsed = time.monotonic() - start
+            if elapsed >= timeout:
+                raise OpenRelayError(
+                    f"Timed out waiting for VM to reach '{target}' "
+                    f"(current: '{vm.status}')"
+                )
+            await asyncio.sleep(poll_interval)

openrelay/types/__init__.py

@@ -0,0 +1,21 @@
+from .gpus import (
+    GpuAvailability,
+    GpuAvailabilityRegion,
+    GpuModel,
+    GpuModelAvailability,
+    GpuPricing,
+    GpuPricingTier,
+)
+from .vms import Vm, VmCreateResponse, VmActionResponse
+
+__all__ = [
+    "GpuAvailability",
+    "GpuAvailabilityRegion",
+    "GpuModel",
+    "GpuModelAvailability",
+    "GpuPricing",
+    "GpuPricingTier",
+    "Vm",
+    "VmCreateResponse",
+    "VmActionResponse",
+]

openrelay/types/gpus.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from .shared import APIModel
+
+
+class GpuModelAvailability(APIModel):
+    total_gpus: int
+    node_count: int
+
+
+class GpuModel(APIModel):
+    """GPU model returned by /v1/gpus/models."""
+
+    id: str
+    name: str
+    manufacturer: str
+    vram_gb: int
+    architecture: Optional[str] = None
+    availability: GpuModelAvailability
+
+
+class GpuAvailabilityRegion(APIModel):
+    gpu_model: str
+    vram_gb: int
+    manufacturer: str
+    region: str
+    location: str
+    country: str
+    tier: str
+    total_gpus: int
+    node_count: int
+
+
+class GpuAvailability(APIModel):
+    timestamp: str
+    availability: List[GpuAvailabilityRegion]
+
+
+class GpuPricingTier(APIModel):
+    price_per_hour: float
+
+
+class GpuPricing(APIModel):
+    gpu_model: str
+    vram_gb: int
+    pricing: Dict[str, GpuPricingTier]

openrelay/types/shared.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel, ConfigDict
+
+
+def to_camel(snake: str) -> str:
+    components = snake.split("_")
+    return components[0] + "".join(x.title() for x in components[1:])
+
+
+class APIModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )

openrelay/types/vms.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from .shared import APIModel
+from .._types import ResourceSize, Tier, VmStatus
+
+
+class VmGpuInfo(APIModel):
+    name: str
+    vram_gb: int
+    price_per_hour_cents: int
+
+
+class VmNodeInfo(APIModel):
+    hostname: str
+    location: str
+
+
+class Vm(APIModel):
+    """VM returned by get endpoint."""
+
+    id: str
+    organization_id: str
+    name: str
+    status: VmStatus
+    gpu_model_id: Optional[str] = None
+    gpu_count: int
+    resource_size: ResourceSize
+    tier: Tier
+    disk_size_gb: int
+    image_url: Optional[str] = None
+    container_port: Optional[int] = None
+    container_command: Optional[List[str]] = None
+    env_vars: Optional[Dict[str, str]] = None
+    health_checks: List[str] = []
+    health_check_path: Optional[str] = None
+    health_check_port: Optional[int] = None
+    privileged: bool = False
+    kernel_modules: Optional[List[str]] = None
+    cloud_init_runcmd: Optional[List[str]] = None
+    template_id: Optional[str] = None
+    endpoint_url: Optional[str] = None
+    preferred_regions: Optional[List[str]] = None
+    allow_fallback: bool = False
+    healthy: bool = False
+    node_id: Optional[str] = None
+    internal_ip: Optional[str] = None
+    port: Optional[int] = None
+    ssh_port: Optional[int] = None
+    persistent_disk_path: Optional[str] = None
+    disk_used_bytes: Optional[int] = None
+    disk_total_bytes: Optional[int] = None
+    started_at: Optional[datetime] = None
+    stopped_at: Optional[datetime] = None
+    created_at: datetime
+    updated_at: datetime
+    gpu_info: Optional[VmGpuInfo] = None
+    node_info: Optional[VmNodeInfo] = None
+    price_per_hour_cents: Optional[int] = None
+
+
+class VmCreateResponse(APIModel):
+    """Response from VM creation."""
+
+    id: str
+    name: str
+    status: VmStatus
+    endpoint_url: Optional[str] = None
+    created_at: datetime
+
+
+class VmActionResponse(APIModel):
+    """Response from VM stop/restart/reboot/delete."""
+
+    success: bool

openrelay_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: openrelay-sdk
+Version: 0.1.0
+Summary: The official Python SDK for the OpenRelay API
+Project-URL: Homepage, https://openrelay.inc
+Project-URL: Documentation, https://docs.openrelay.inc
+Project-URL: Repository, https://github.com/OpenRelayInc/OpenRelay
+Project-URL: Issues, https://github.com/OpenRelayInc/OpenRelay/issues
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx<1,>=0.25.0
+Requires-Dist: pydantic<3,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OpenRelay Python SDK
+
+The official Python SDK for the [OpenRelay](https://openrelay.inc) API.
+
+## Installation
+
+```bash
+pip install openrelay-sdk
+```
+
+The package imports as `openrelay`. The unrelated `openrelay` distribution on
+PyPI also provides a top-level `openrelay` module, so install `openrelay-sdk`,
+and do not install both into the same environment.
+
+From a checkout of this repository: `pip install ./sdks/python`.
+
+## Quick Start
+
+```python
+import openrelay
+
+client = openrelay.Client(api_key="or_your_api_key")
+
+# List available GPUs
+gpus = client.gpus.list()
+
+# Create a VM
+vm = client.vms.create(
+    name="dev-box",
+    ssh_key_ids=["your-ssh-key-id"],
+    gpu_type="rtx-4090",
+    gpu_count=1,
+    disk_size_gb=100,
+)
+
+# Wait for it to be ready
+vm = client.vms.wait_for_status(vm.id)
+print(f"VM running at: {vm.endpoint_url}")
+```
+
+## Async Usage
+
+```python
+import asyncio
+import openrelay
+
+async def main():
+    async with openrelay.AsyncClient(api_key="or_your_api_key") as client:
+        vm = await client.vms.get("your-vm-id")
+        print(vm.status)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+The client accepts these parameters:
+
+| Parameter | Env Variable | Default |
+|-----------|-------------|---------|
+| `api_key` | `OPENRELAY_API_KEY` | Required |
+| `base_url` | `OPENRELAY_API_URL` | `https://api.openrelay.inc` |
+| `timeout` | (none) | `60.0` seconds |
+| `max_retries` | (none) | `2` |
+
+The `orl` CLI reads the same two variables.
+
+## License
+
+MIT

openrelay_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+openrelay/__init__.py,sha256=qTg21KjF-BbvhJkNwl3BNeNnM-NKYMrclehWyJ3YK1A,1130
+openrelay/_base_client.py,sha256=zH--VRw08GKliaDYOSnGLizrSjTz-eNeAX6kFjjQz4I,5575
+openrelay/_client.py,sha256=gKBNCql7SbYebd1FytvZDkqhIl2lXGcbi0P8IIowcDA,7581
+openrelay/_constants.py,sha256=eOCheHCQssPNT-3mDqRg5F0imnAunDBok1BANpZT83Y,849
+openrelay/_exceptions.py,sha256=fHy2QmSAFGb1AXCl2leWocXNTWo0d1Qq4aSkuQIL350,1635
+openrelay/_types.py,sha256=8OEwdQxplL-9KhS7wV_9v5wT2sfPoiELQUk3zVTmHCk,256
+openrelay/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+openrelay/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openrelay/resources/__init__.py,sha256=AhzKNY7t9g_aV0TRNqQbMKNeW57ybTLRBv-Wu7TNmMY,152
+openrelay/resources/gpus.py,sha256=oNhfSGmsPPK4tJeWtZp5rzvFW83e1efw9PT7-1D97jk,3271
+openrelay/resources/vms.py,sha256=wJyOwkMvMZUXvsVcCRKmu_cJAucRKW6pbdplg0AoeL0,12664
+openrelay/types/__init__.py,sha256=a_1kWizar876P8CjSW36kyACcizBD6hnGHQcsor31mA,411
+openrelay/types/gpus.py,sha256=wdlZpNZLDSBRtb0WOdJL4irFAFMyAGZKhjGO88mRcps,876
+openrelay/types/shared.py,sha256=UKYfKdg2_ZdexNfJKVQyNOQz7_C7cjTTrND1qzcN1U8,343
+openrelay/types/vms.py,sha256=msWPxym1dpwLrclcBqF1YXwxxKVW8KnTkXqM1F2ptWo,2040
+openrelay_sdk-0.1.0.dist-info/METADATA,sha256=25eTZDg0IgFyLgtK5k_PNEOS2vJDRb2z-hfCHxYYw_M,2744
+openrelay_sdk-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+openrelay_sdk-0.1.0.dist-info/RECORD,,

openrelay_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any