vers-sdk 0.1.1__py3-none-any.whl

vers_sdk/__init__.py

@@ -0,0 +1,34 @@
+# Generated by Sterling SDK Generator
+# Orchestrator Control Plane API v0.1.0
+
+from .client import VersSdkClient
+from .errors import (
+    VersSDKError,
+    APIError,
+    APIConnectionError,
+    APIConnectionTimeoutError,
+    BadRequestError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    ConflictError,
+    UnprocessableEntityError,
+    RateLimitError,
+    InternalServerError,
+)
+
+__all__ = [
+    "VersSdkClient",
+    "VersSDKError",
+    "APIError",
+    "APIConnectionError",
+    "APIConnectionTimeoutError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+]

vers_sdk/client.py

@@ -0,0 +1,529 @@
+# Generated by Sterling SDK Generator
+# Orchestrator Control Plane API v0.1.0
+
+import asyncio
+import calendar
+import email.utils
+import logging
+import os
+import random
+import time as _time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import httpx
+
+from .errors import APIError, APIConnectionError
+from .models import *  # noqa: F403
+
+
+@dataclass
+class RequestOptions:
+    """Per-request options that override client defaults."""
+
+    #: Additional headers to send with the request.
+    #: Set a header to None to remove it.
+    headers: dict[str, str | None] | None = None
+
+    #: Request timeout in seconds. Overrides the client-level timeout.
+    timeout: float | None = None
+
+logger = logging.getLogger("vers_sdk")
+
+_LOG_LEVEL_MAP = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warn": logging.WARNING,
+    "error": logging.ERROR,
+    "off": logging.CRITICAL + 1,
+}
+
+
+def _configure_logger() -> None:
+    env_level = os.environ.get("VERS_LOG", "warn").lower()
+    level = _LOG_LEVEL_MAP.get(env_level, logging.WARNING)
+    logger.setLevel(level)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(asctime)s [vers_sdk %(levelname)s] %(message)s"))
+        logger.addHandler(handler)
+
+
+_configure_logger()
+
+
+# Status codes that are retryable even though they are 4xx
+RETRYABLE_STATUS_CODES = {408, 409, 429}
+
+
+def _is_retryable_status(status: int) -> bool:
+    return status >= 500 or status in RETRYABLE_STATUS_CODES
+
+
+def _retry_delay(attempt: int) -> float:
+    base = 0.5 * (2 ** attempt)
+    jitter = random.random() * base * 0.25
+    return base + jitter
+
+
+def _parse_retry_after(header_value: Optional[str]) -> Optional[float]:
+    if header_value is None:
+        return None
+    try:
+        delay = float(header_value)
+        return min(max(delay, 0.0), 60.0)
+    except (ValueError, OverflowError):
+        pass
+    parsed = email.utils.parsedate(header_value)
+    if parsed is not None:
+        retry_time = calendar.timegm(parsed)
+        delay = retry_time - _time.time()
+        return min(max(delay, 0.0), 60.0)
+    return None
+
+
+class VersSdkClient:
+    """Client for Orchestrator Control Plane API"""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        headers: Optional[dict[str, str | None]] = None,
+        max_retries: int = 2,
+        timeout: float = 30.0,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ):
+        self.base_url = base_url or os.environ.get("VERS_BASE_URL", "https://api.vers.sh")
+        self.api_key = api_key or os.environ.get("VERS_API_KEY")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._custom_headers: dict[str, str | None] = headers or {}
+        if http_client is not None:
+            self._client = http_client
+        else:
+            import platform as _platform
+            default_headers: dict[str, str] = {
+                "User-Agent": f"vers-sdk/0.1.1 python/{_platform.python_version()} {_platform.system().lower()}/{_platform.machine()}",
+            }
+            if self.api_key:
+                default_headers["Authorization"] = f"Bearer {self.api_key}"
+            merged = self._merge_headers(default_headers, self._custom_headers)
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=merged,
+                timeout=self.timeout,
+            )
+
+    @staticmethod
+    def _merge_headers(*sources: Optional[dict[str, str | None]]) -> dict[str, str]:
+        """Merge header dicts. Later sources override earlier ones (case-insensitive).
+        A ``None`` value removes the header."""
+        merged: dict[str, str] = {}
+        for source in sources:
+            if source is None:
+                continue
+            for key, value in source.items():
+                if value is None:
+                    # Remove header (case-insensitive)
+                    merged = {
+                        k: v for k, v in merged.items()
+                        if k.lower() != key.lower()
+                    }
+                else:
+                    merged[key] = value
+        return merged
+
+    def _check_response(self, response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        body: Any = None
+        message: str | None = None
+        try:
+            body = response.json()
+        except Exception:
+            message = response.text
+        headers = dict(response.headers)
+        raise APIError.generate(
+            status=response.status_code,
+            body=body,
+            message=message,
+            headers=headers,
+        )
+
+    async def _request(self, method: str, path: str, options: RequestOptions | None = None, **kwargs: Any) -> httpx.Response:
+        logger.debug("request: %s %s", method, path)
+
+        req_headers: dict[str, str] = kwargs.pop("headers", {})
+        if method.upper() in ("POST", "PUT", "PATCH", "DELETE"):
+            req_headers["X-Idempotency-Key"] = str(uuid.uuid4())
+        # Apply per-request header overrides
+        if options and options.headers:
+            for k, v in options.headers.items():
+                if v is None:
+                    req_headers.pop(k, None)
+                else:
+                    req_headers[k] = v
+        if req_headers:
+            kwargs["headers"] = req_headers
+        effective_timeout = options.timeout if options and options.timeout is not None else None
+
+        last_exc: Optional[Exception] = None
+        retry_after_used = False
+        for attempt in range(self.max_retries + 1):
+            if attempt > 0 and not retry_after_used:
+                logger.info("retry attempt %d/%d for %s %s", attempt, self.max_retries, method, path)
+                await asyncio.sleep(_retry_delay(attempt - 1))
+            retry_after_used = False
+            try:
+                req_kwargs = dict(kwargs)
+                if effective_timeout is not None:
+                    req_kwargs["timeout"] = effective_timeout
+                response = await self._client.request(method, path, **req_kwargs)
+                # Remove headers that were set to None
+                logger.debug("response: %d for %s %s", response.status_code, method, path)
+                if _is_retryable_status(response.status_code) and attempt < self.max_retries:
+                    ra_delay = _parse_retry_after(response.headers.get("retry-after"))
+                    if ra_delay is not None:
+                        retry_after_used = True
+                        logger.info("retry attempt %d/%d for %s %s (retry-after: %.1fs)", attempt + 1, self.max_retries, method, path, ra_delay)
+                        await asyncio.sleep(ra_delay)
+                    last_exc = Exception(f"HTTP {response.status_code}")
+                    continue
+                self._check_response(response)
+                return response
+            except APIError:
+                raise
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                logger.error("connection error: %s %s - %s", method, path, exc)
+                if attempt == self.max_retries:
+                    raise APIConnectionError(cause=exc) from exc
+                last_exc = exc
+        raise last_exc  # type: ignore[misc]
+
+    async def resize_vm_disk(self, vm_id: str, body: dict[str, Any], params: ResizeVmDiskParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_id}/disk"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.skip_wait_boot is not None:
+                query["skip_wait_boot"] = params.skip_wait_boot
+        return await self._request("PATCH", path, options, json=body, params=query)
+
+    async def exec_vm_stream_attach(self, vm_id: str, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_id}/exec/stream/attach"
+        return await self._request("POST", path, options, json=body)
+
+    async def create_new_root_vm(self, body: dict[str, Any], params: CreateNewRootVmParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/vm/new_root"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.wait_boot is not None:
+                query["wait_boot"] = params.wait_boot
+        return await self._request("POST", path, options, json=body, params=query)
+
+    async def vm_logs(self, vm_id: str, params: VmLogsParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_id}/logs"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.offset is not None:
+                query["offset"] = params.offset
+            if params.max_entries is not None:
+                query["max_entries"] = params.max_entries
+            if params.stream is not None:
+                query["stream"] = params.stream
+        return await self._request("GET", path, options, params=query)
+
+    async def branch_by_ref(self, repo_name: str, tag_name: str, body: dict[str, Any] | None = None, params: BranchByRefParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/branch/by_ref/{repo_name}/{tag_name}"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.count is not None:
+                query["count"] = params.count
+        return await self._request("POST", path, options, json=body, params=query)
+
+    async def list_public_commits(self, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/commits/public"
+        return await self._request("GET", path, options)
+
+    async def list_public_repo_tags(self, org_name: str, repo_name: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/public/repositories/{org_name}/{repo_name}/tags"
+        return await self._request("GET", path, options)
+
+    async def branch_by_tag(self, tag_name: str, body: dict[str, Any] | None = None, params: BranchByTagParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/branch/by_tag/{tag_name}"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.count is not None:
+                query["count"] = params.count
+        return await self._request("POST", path, options, json=body, params=query)
+
+    async def branch_vm(self, vm_or_commit_id: str, body: dict[str, Any] | None = None, params: BranchVmParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_or_commit_id}/branch"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.keep_paused is not None:
+                query["keep_paused"] = params.keep_paused
+            if params.skip_wait_boot is not None:
+                query["skip_wait_boot"] = params.skip_wait_boot
+            if params.count is not None:
+                query["count"] = params.count
+        return await self._request("POST", path, options, json=body, params=query)
+
+    async def get_repo_tag(self, repo_name: str, tag_name: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/repositories/{repo_name}/tags/{tag_name}"
+        return await self._request("GET", path, options)
+
+    async def delete_repo_tag(self, repo_name: str, tag_name: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/repositories/{repo_name}/tags/{tag_name}"
+        return await self._request("DELETE", path, options)
+
+    async def update_repo_tag(self, repo_name: str, tag_name: str, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/repositories/{repo_name}/tags/{tag_name}"
+        return await self._request("PATCH", path, options, json=body)
+
+    async def get_repository(self, repo_name: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/repositories/{repo_name}"
+        return await self._request("GET", path, options)
+
+    async def delete_repository(self, repo_name: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/repositories/{repo_name}"
+        return await self._request("DELETE", path, options)
+
+    async def list_parent_commits(self, commit_id: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/commits/{commit_id}/parents"
+        return await self._request("GET", path, options)
+
+    async def update_vm_state(self, vm_id: str, body: dict[str, Any], params: UpdateVmStateParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_id}/state"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.skip_wait_boot is not None:
+                query["skip_wait_boot"] = params.skip_wait_boot
+        return await self._request("PATCH", path, options, json=body, params=query)
+
+    async def fork_repository(self, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/repositories/fork"
+        return await self._request("POST", path, options, json=body)
+
+    async def list_repositories(self, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/repositories"
+        return await self._request("GET", path, options)
+
+    async def create_repository(self, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/repositories"
+        return await self._request("POST", path, options, json=body)
+
+    async def restore_from_commit(self, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/vm/from_commit"
+        return await self._request("POST", path, options, json=body)
+
+    async def get_domain(self, domain_id: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/domains/{domain_id}"
+        return await self._request("GET", path, options)
+
+    async def delete_domain(self, domain_id: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/domains/{domain_id}"
+        return await self._request("DELETE", path, options)
+
+    async def list_tags(self, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/commit_tags"
+        return await self._request("GET", path, options)
+
+    async def create_tag(self, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/commit_tags"
+        return await self._request("POST", path, options, json=body)
+
+    async def list_public_repositories(self, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/public/repositories"
+        return await self._request("GET", path, options)
+
+    async def get_public_repo_tag(self, org_name: str, repo_name: str, tag_name: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/public/repositories/{org_name}/{repo_name}/tags/{tag_name}"
+        return await self._request("GET", path, options)
+
+    async def get_vm_metadata(self, vm_id: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_id}/metadata"
+        return await self._request("GET", path, options)
+
+    async def list_env_vars(self, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/env_vars"
+        return await self._request("GET", path, options)
+
+    async def set_env_vars(self, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/env_vars"
+        return await self._request("PUT", path, options, json=body)
+
+    async def delete_vm(self, vm_id: str, params: DeleteVmParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_id}"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.skip_wait_boot is not None:
+                query["skip_wait_boot"] = params.skip_wait_boot
+        return await self._request("DELETE", path, options, params=query)
+
+    async def list_commits(self, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/commits"
+        return await self._request("GET", path, options)
+
+    async def get_tag(self, tag_name: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/commit_tags/{tag_name}"
+        return await self._request("GET", path, options)
+
+    async def delete_tag(self, tag_name: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/commit_tags/{tag_name}"
+        return await self._request("DELETE", path, options)
+
+    async def update_tag(self, tag_name: str, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/commit_tags/{tag_name}"
+        return await self._request("PATCH", path, options, json=body)
+
+    async def branch_by_vm(self, vm_id: str, body: dict[str, Any] | None = None, params: BranchByVmParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/branch/by_vm/{vm_id}"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.keep_paused is not None:
+                query["keep_paused"] = params.keep_paused
+            if params.skip_wait_boot is not None:
+                query["skip_wait_boot"] = params.skip_wait_boot
+            if params.count is not None:
+                query["count"] = params.count
+        return await self._request("POST", path, options, json=body, params=query)
+
+    async def delete_env_var(self, key: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/env_vars/{key}"
+        return await self._request("DELETE", path, options)
+
+    async def exec_vm_stream(self, vm_id: str, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_id}/exec/stream"
+        return await self._request("POST", path, options, json=body)
+
+    async def commit_vm(self, vm_id: str, body: dict[str, Any] | None = None, params: CommitVmParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_id}/commit"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.keep_paused is not None:
+                query["keep_paused"] = params.keep_paused
+            if params.skip_wait_boot is not None:
+                query["skip_wait_boot"] = params.skip_wait_boot
+        return await self._request("POST", path, options, json=body, params=query)
+
+    async def delete_commit(self, commit_id: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/commits/{commit_id}"
+        return await self._request("DELETE", path, options)
+
+    async def update_commit(self, commit_id: str, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/commits/{commit_id}"
+        return await self._request("PATCH", path, options, json=body)
+
+    async def list_repo_tags(self, repo_name: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/repositories/{repo_name}/tags"
+        return await self._request("GET", path, options)
+
+    async def create_repo_tag(self, repo_name: str, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/repositories/{repo_name}/tags"
+        return await self._request("POST", path, options, json=body)
+
+    async def ssh_key(self, vm_id: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_id}/ssh_key"
+        return await self._request("GET", path, options)
+
+    async def exec_vm(self, vm_id: str, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_id}/exec"
+        return await self._request("POST", path, options, json=body)
+
+    async def set_repository_visibility(self, repo_name: str, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/repositories/{repo_name}/visibility"
+        return await self._request("PATCH", path, options, json=body)
+
+    async def list_vms(self, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/vms"
+        return await self._request("GET", path, options)
+
+    async def list_domains(self, params: ListDomainsParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/domains"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.vm_id is not None:
+                query["vm_id"] = params.vm_id
+        return await self._request("GET", path, options, params=query)
+
+    async def create_domain(self, body: dict[str, Any], options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = "/api/v1/domains"
+        return await self._request("POST", path, options, json=body)
+
+    async def vm_status(self, vm_id: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/{vm_id}/status"
+        return await self._request("GET", path, options)
+
+    async def get_public_repository(self, org_name: str, repo_name: str, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/public/repositories/{org_name}/{repo_name}"
+        return await self._request("GET", path, options)
+
+    async def branch_by_commit(self, commit_id: str, body: dict[str, Any] | None = None, params: BranchByCommitParams | None = None, options: RequestOptions | None = None) -> httpx.Response:
+        """"""
+        path = f"/api/v1/vm/branch/by_commit/{commit_id}"
+        query: dict[str, Any] = {}
+        if params is not None:
+            if params.count is not None:
+                query["count"] = params.count
+        return await self._request("POST", path, options, json=body, params=query)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "VersSdkClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

vers_sdk/errors.py

@@ -0,0 +1,132 @@
+# Generated by Sterling SDK Generator
+# Orchestrator Control Plane API v0.1.0
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class VersSDKError(Exception):
+    """Base error class for the VersSdk SDK."""
+    pass
+
+
+class APIError(VersSDKError):
+    """Error returned when the API responds with a non-success status code."""
+
+    status: int | None
+    headers: dict[str, str] | None
+    body: Any
+
+    def __init__(
+        self,
+        status: int | None,
+        body: Any = None,
+        message: str | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self.status = status
+        self.headers = headers
+        self.body = body
+        super().__init__(self._make_message(status, body, message))
+
+    @staticmethod
+    def _make_message(status: int | None, body: Any, message: str | None) -> str:
+        msg = None
+        if isinstance(body, dict) and "message" in body:
+            msg = body["message"] if isinstance(body["message"], str) else str(body["message"])
+        elif body is not None:
+            msg = str(body)
+        elif message is not None:
+            msg = message
+
+        if status and msg:
+            return f"{status} {msg}"
+        if status:
+            return f"{status} status code (no body)"
+        if msg:
+            return msg
+        return "(no status code or body)"
+
+    @classmethod
+    def generate(
+        cls,
+        status: int | None,
+        body: Any = None,
+        message: str | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> APIError:
+        if status is None or headers is None:
+            return APIConnectionError(message=message)
+
+        error_map: dict[int, type[APIError]] = {
+            400: BadRequestError,
+            401: AuthenticationError,
+            403: PermissionDeniedError,
+            404: NotFoundError,
+            409: ConflictError,
+            422: UnprocessableEntityError,
+            429: RateLimitError,
+        }
+
+        error_cls = error_map.get(status)
+        if error_cls is not None:
+            return error_cls(status=status, body=body, message=message, headers=headers)
+        if status >= 500:
+            return InternalServerError(status=status, body=body, message=message, headers=headers)
+        return APIError(status=status, body=body, message=message, headers=headers)
+
+
+class APIConnectionError(APIError):
+    """Error thrown when a connection to the API cannot be established."""
+
+    def __init__(self, message: str | None = None, cause: BaseException | None = None) -> None:
+        super().__init__(status=None, body=None, message=message or "Connection error.")
+        self.__cause__ = cause
+
+
+class APIConnectionTimeoutError(APIConnectionError):
+    """Error thrown when a request times out."""
+
+    def __init__(self, message: str | None = None) -> None:
+        super().__init__(message=message or "Request timed out.")
+
+
+class BadRequestError(APIError):
+    """400 Bad Request"""
+    pass
+
+
+class AuthenticationError(APIError):
+    """401 Unauthorized"""
+    pass
+
+
+class PermissionDeniedError(APIError):
+    """403 Forbidden"""
+    pass
+
+
+class NotFoundError(APIError):
+    """404 Not Found"""
+    pass
+
+
+class ConflictError(APIError):
+    """409 Conflict"""
+    pass
+
+
+class UnprocessableEntityError(APIError):
+    """422 Unprocessable Entity"""
+    pass
+
+
+class RateLimitError(APIError):
+    """429 Too Many Requests"""
+    pass
+
+
+class InternalServerError(APIError):
+    """5xx Internal Server Error"""
+    pass

vers_sdk/models.py

@@ -0,0 +1,545 @@
+# Generated by Sterling SDK Generator
+# Orchestrator Control Plane API v0.1.0
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional, Union
+
+@dataclass
+class ForkRepositoryResponse:
+    """Response body for POST /api/v1/repositories/fork"""
+    #: The new commit in your org (snapshot of the forked VM)
+    commit_id: str
+    #: Full reference: repo_name:tag_name
+    reference: str
+    #: The new repository name in your org
+    repo_name: str
+    #: The tag name pointing to the forked commit
+    tag_name: str
+    #: The new VM that was created from the fork
+    vm_id: str
+
+@dataclass
+class VmSshKeyResponse:
+    """Response body for GET /api/vm/{vm_id}/ssh_key"""
+    #: The SSH port that will be DNAT'd to the VM's netns (and, in turn, to its TAP device)
+    ssh_port: int
+    #: Private SSH key in stringified OpenSSH format
+    ssh_private_key: str
+
+class VmState(str, Enum):
+    """The state of a VM"""
+    BOOTING = "booting"
+    RUNNING = "running"
+    PAUSED = "paused"
+    SLEEPING = "sleeping"
+    DEAD = "dead"
+
+class VmUpdateStateEnum(str, Enum):
+    """Possible options for the state requested in PATCH /api/vm/{vm_id}/state"""
+    PAUSED = "Paused"
+    RUNNING = "Running"
+
+@dataclass
+class VmUpdateStateRequest:
+    """Request body for PATCH /api/vm/{vm_id}/state"""
+    #: The requested state for the VM
+    state: VmUpdateStateEnum
+
+@dataclass
+class ErrorResponse:
+    """"""
+    #: Reason of error
+    error: Optional[str] = None
+    #: Is always: false
+    success: Optional[bool] = None
+
+@dataclass
+class UpdateCommitRequest:
+    """Request body for PATCH /commits/{commit_id}"""
+    is_public: bool
+
+@dataclass
+class EnvVarsResponse:
+    """Response body for GET /env_vars and PUT /env_vars."""
+    #: All environment variables currently set for the authenticated user.
+    vars: Any
+
+@dataclass
+class CreateRepositoryResponse:
+    """Response body for POST /api/v1/repositories"""
+    #: The name of the repository
+    name: str
+    #: The ID of the newly created repository
+    repo_id: str
+
+@dataclass
+class CreateRepositoryRequest:
+    """Request body for POST /api/v1/repositories"""
+    #: Optional description of the repository
+    description: Optional[Any] = None
+    #: The name of the repository (alphanumeric, hyphens, underscores, dots, 1-64 chars)
+    name: str
+
+@dataclass
+class DomainResponse:
+    """Response type for domain operations."""
+    created_at: str
+    domain: str
+    domain_id: str
+    vm_id: str
+
+@dataclass
+class PublicRepositoryInfo:
+    """Public repository information (includes owner org name for namespacing)"""
+    #: When the repository was created
+    created_at: str
+    #: Optional description
+    description: Optional[Any] = None
+    #: Full reference: org_name/repo_name
+    full_name: str
+    #: The repository name
+    name: str
+    #: The owning organization's name (namespace)
+    org_name: str
+    #: The repository's unique identifier
+    repo_id: str
+
+@dataclass
+class ListTagsResponse:
+    """Response body for GET /api/v1/commit_tags"""
+    #: List of all tags in the user's organization
+    tags: list[TagInfo]
+
+@dataclass
+class CreateRepoTagRequest:
+    """Request body for creating a tag within a repository: POST /api/v1/repositories/{repo_name}/tags"""
+    #: The commit ID this tag should point to
+    commit_id: str
+    #: Optional description of what this tag represents
+    description: Optional[Any] = None
+    #: The tag name (e.g. 'latest', 'v1.0')
+    tag_name: str
+
+@dataclass
+class ForkRepositoryRequest:
+    """Request body for POST /api/v1/repositories/fork"""
+    #: Name for the new repository in your org (defaults to source_repo if omitted)
+    repo_name: Optional[Any] = None
+    #: The organization that owns the source public repository
+    source_org: str
+    #: The source repository name
+    source_repo: str
+    #: The tag to fork (e.g. 'latest', 'v1.0')
+    source_tag: str
+    #: Tag name in the new repo (defaults to source_tag if omitted)
+    tag_name: Optional[Any] = None
+
+@dataclass
+class VmCommitEntity:
+    """"""
+    created_at: str
+    description: Optional[Any] = None
+    #: The commit that this commit's parent VM was started from, if any. Intended to optimize traversing the commit tree.
+    grandparent_commit_id: Optional[Any] = None
+    id: str
+    #: Whether this commit is publicly accessible (readable/restorable by anyone).
+    is_public: bool
+    name: str
+    #: api key id.
+    owner_id: str
+    #: The VM that this commit was created from, if any.
+    parent_vm_id: Optional[Any] = None
+
+@dataclass
+class VmExecLogQuery:
+    """Query params for GET /api/vm/{vm_id}/exec/logs"""
+    #: Maximum number of entries to return (server applies caps).
+    max_entries: Optional[Any] = None
+    #: Byte offset into the log file to start reading from.
+    offset: Optional[Any] = None
+    #: Skip waiting for boot state (mirrors exec).
+    skip_wait_boot: Optional[Any] = None
+    stream: Optional[Any] = None
+
+@dataclass
+class TagInfo:
+    """Tag information returned in list and get operations"""
+    #: The commit ID this tag currently points to
+    commit_id: str
+    #: When the tag was created
+    created_at: str
+    #: Optional description of what this tag represents
+    description: Optional[Any] = None
+    #: The tag's unique identifier
+    tag_id: str
+    #: The name of the tag
+    tag_name: str
+    #: When the tag was last updated (moved to different commit or description changed)
+    updated_at: str
+
+@dataclass
+class ListCommitsResponse:
+    """"""
+    commits: list[CommitInfo]
+    limit: int
+    offset: int
+    total: int
+
+@dataclass
+class ListRepoTagsResponse:
+    """Response body for GET /api/v1/repositories/{repo_name}/tags"""
+    #: The repository name
+    repository: str
+    #: List of tags in this repository
+    tags: list[RepoTagInfo]
+
+@dataclass
+class VmExecLogEntry:
+    """Individual log entry describing emitted stdout/stderr chunk."""
+    #: Base64-encoded bytes from stdout/stderr chunk.
+    data_b64: str
+    exec_id: Optional[Any] = None
+    stream: VmExecLogStream
+    timestamp: str
+
+class VmExecLogStream(str, Enum):
+    """Streams available for exec logging."""
+    STDOUT = "stdout"
+    STDERR = "stderr"
+
+@dataclass
+class VmExecResponse:
+    """Response body for POST /api/vm/{vm_id}/exec"""
+    #: Exec identifier associated with this run.
+    exec_id: Optional[Any] = None
+    #: Exit code returned by the command.
+    exit_code: int
+    #: UTF-8 decoded stderr (lossy).
+    stderr: str
+    #: UTF-8 decoded stdout (lossy).
+    stdout: str
+
+@dataclass
+class VmExecStreamAttachRequest:
+    """Request body for POST /api/vm/{vm_id}/exec/stream/attach"""
+    #: Optional cursor to resume from (exclusive). If omitted, the full retained backlog is replayed.
+    cursor: Optional[Any] = None
+    #: Identifier of the exec stream session to reattach to.
+    exec_id: str
+    #: Start streaming after the latest retained chunk (ignores cursor).
+    from_latest: Optional[Any] = None
+
+@dataclass
+class VmExecRequest:
+    """Request body for POST /api/vm/{vm_id}/exec"""
+    #: Command and arguments to execute.
+    command: list[str]
+    #: Optional environment variables to set for the process.
+    env: Optional[Any] = None
+    #: Optional exec identifier for tracking.
+    exec_id: Optional[Any] = None
+    #: Optional stdin payload passed to the command.
+    stdin: Optional[Any] = None
+    #: Timeout in seconds (0 = no timeout).
+    timeout_secs: Optional[Any] = None
+    #: Optional working directory for the command.
+    working_dir: Optional[Any] = None
+
+@dataclass
+class NewVmsResponse:
+    """"""
+    vms: list[NewVmResponse]
+
+@dataclass
+class SetRepositoryVisibilityRequest:
+    """Request body for PATCH /api/v1/repositories/{repo_name}/visibility"""
+    #: Whether the repository should be publicly visible
+    is_public: bool
+
+@dataclass
+class UpdateRepoTagRequest:
+    """Request body for PATCH /api/v1/repositories/{repo_name}/tags/{tag_name}"""
+    #: Optional new commit ID to move the tag to
+    commit_id: Optional[Any] = None
+    #: Optional new description for the tag. Send `null` to clear.
+    description: Optional[Any] = None
+
+@dataclass
+class NewVmResponse:
+    """Response body for new VM requests (new_root, from_commit, branch)"""
+    vm_id: str
+
+@dataclass
+class ListPublicRepositoriesResponse:
+    """Response body for GET /api/v1/public/repositories"""
+    repositories: list[PublicRepositoryInfo]
+
+@dataclass
+class CreateTagRequest:
+    """Request body for POST /api/v1/commit_tags"""
+    #: The commit ID this tag should point to
+    commit_id: str
+    #: Optional description of what this tag represents
+    description: Optional[Any] = None
+    #: The name of the tag (alphanumeric, hyphens, underscores, dots, 1-64 chars)
+    tag_name: str
+
+@dataclass
+class FromCommitVmRequestCommitIdVariant:
+    """Request body for POST /api/v1/vm/from_commit"""
+    commit_id: str
+
+@dataclass
+class FromCommitVmRequestTagNameVariant:
+    """Request body for POST /api/v1/vm/from_commit"""
+    tag_name: str
+
+@dataclass
+class FromCommitVmRequestRefVariant:
+    """Request body for POST /api/v1/vm/from_commit"""
+    ref: str
+
+FromCommitVmRequest = Union[FromCommitVmRequestCommitIdVariant, FromCommitVmRequestTagNameVariant, FromCommitVmRequestRefVariant]
+
+@dataclass
+class CreateRepoTagResponse:
+    """Response body for POST /api/v1/repositories/{repo_name}/tags"""
+    #: The commit ID this tag points to
+    commit_id: str
+    #: Full reference in image_name:tag format
+    reference: str
+    #: The ID of the newly created tag
+    tag_id: str
+
+@dataclass
+class CommitInfo:
+    """"""
+    commit_id: str
+    created_at: str
+    description: Optional[Any] = None
+    grandparent_commit_id: Optional[Any] = None
+    is_public: bool
+    name: str
+    owner_id: str
+    parent_vm_id: Optional[Any] = None
+
+@dataclass
+class CreateDomainRequest:
+    """Request body for POST /api/v1/domains"""
+    domain: str
+    vm_id: str
+
+@dataclass
+class DeleteDomainResponse:
+    """Response body for DELETE /api/v1/domains/{domain_id}"""
+    domain_id: str
+
+@dataclass
+class ListRepositoriesResponse:
+    """Response body for GET /api/v1/repositories"""
+    #: List of all repositories in the user's organization
+    repositories: list[RepositoryInfo]
+
+@dataclass
+class RepositoryInfo:
+    """Repository information returned in list and get operations"""
+    #: When the repository was created
+    created_at: str
+    #: Optional description
+    description: Optional[Any] = None
+    #: Whether this repository is publicly visible
+    is_public: bool
+    #: The repository name
+    name: str
+    #: The repository's unique identifier
+    repo_id: str
+
+@dataclass
+class UpdateTagRequest:
+    """Request body for PATCH /api/v1/commit_tags/{tag_name}  For `description`: - Field absent from JSON → don't change the description - Field present as `null` → clear the description - Field present as `'text'` → set the description to 'text'"""
+    #: Optional new commit ID to move the tag to
+    commit_id: Optional[Any] = None
+    #: Optional new description for the tag. Send `null` to clear an existing description.
+    description: Optional[Any] = None
+
+@dataclass
+class NewRootRequest:
+    """"""
+    vm_config: VmCreateVmConfig
+
+@dataclass
+class SetEnvVarsRequest:
+    """Request body for PUT /env_vars — sets (upserts) one or more environment variables.  # Lifecycle model  Environment variables are written to `/etc/environment` inside a VM **once at boot time** via a vsock `WriteFile` request. They are **not** live-synced to running VMs. This is intentional: VMs are ephemeral (create → use → destroy/branch), so env var changes naturally take effect on the next VM.  The `replace` flag exists so callers can atomically express 'I want exactly these variables and nothing else' without having to DELETE each stale key individually. Without it, the only way to remove a variable from future VMs is a separate `DELETE /env_vars/{key}` call per key."""
+    #: If true, delete all existing variables before writing the new set. This gives 'set exactly these vars' semantics. Default: false (upsert).
+    replace: Optional[bool] = None
+    #: Key-value pairs to set. Keys must be valid shell identifiers (`^[A-Za-z_][A-Za-z0-9_]*$`, max 256 chars). Values max 8192 chars.  When `replace` is false (default): existing keys are overwritten, keys not mentioned are left untouched (upsert semantics).  When `replace` is true: all existing variables are deleted first, then only the provided vars are stored (replace-all semantics).
+    vars: Any
+
+@dataclass
+class VM:
+    """"""
+    created_at: str
+    owner_id: str
+    state: VmState
+    vm_id: str
+
+@dataclass
+class VmCreateVmConfig:
+    """Struct representing configuration options common to all VMs"""
+    #: The disk size, in MiB.
+    fs_size_mib: Optional[Any] = None
+    #: The filesystem base image name. Currently, must be 'default'
+    image_name: Optional[Any] = None
+    #: The kernel name. Currently, must be 'default.bin'
+    kernel_name: Optional[Any] = None
+    #: The RAM size, in MiB.
+    mem_size_mib: Optional[Any] = None
+    #: How many vCPUs to allocate to this VM (and its children)
+    vcpu_count: Optional[Any] = None
+
+@dataclass
+class VmDeleteResponse:
+    """Response body for DELETE /api/vm/{vm_id}"""
+    vm_id: str
+
+@dataclass
+class CreateTagResponse:
+    """Response body for POST /api/v1/commit_tags"""
+    #: The commit ID this tag points to
+    commit_id: str
+    #: The ID of the newly created tag
+    tag_id: str
+    #: The name of the tag
+    tag_name: str
+
+@dataclass
+class RepoTagInfo:
+    """Tag information within a repository context"""
+    #: The commit ID this tag currently points to
+    commit_id: str
+    #: When the tag was created
+    created_at: str
+    #: Optional description
+    description: Optional[Any] = None
+    #: Full reference in image_name:tag format
+    reference: str
+    #: The tag's unique identifier
+    tag_id: str
+    #: The tag name
+    tag_name: str
+    #: When the tag was last updated
+    updated_at: str
+
+@dataclass
+class VmExecLogResponse:
+    """Response for exec log tail requests."""
+    #: Returned log entries.
+    entries: list[VmExecLogEntry]
+    #: True when the end of file was reached.
+    eof: bool
+    #: Next byte offset to continue from.
+    next_offset: int
+
+@dataclass
+class VmMetadataResponse:
+    """Response for GET /api/v1/vm/{vm_id}/metadata"""
+    created_at: str
+    deleted_at: Optional[Any] = None
+    grandparent_vm_id: Optional[Any] = None
+    ip: str
+    owner_id: str
+    parent_commit_id: Optional[Any] = None
+    state: VmState
+    vm_id: str
+
+@dataclass
+class VmResizeDiskRequest:
+    """Request body for PATCH /api/vm/{vm_id}/disk"""
+    #: The new disk size in MiB. Must be strictly greater than the current size.
+    fs_size_mib: int
+
+@dataclass
+class VmCommitResponse:
+    """The response body for POST /api/vm/{vm_id}/commit"""
+    #: The UUID of the newly-created commit
+    commit_id: str
+
+
+# ── Params types for operations with query parameters ───────────────
+
+@dataclass
+class ResizeVmDiskParams:
+    """If true, return an error immediately if the VM is still booting. Default: false"""
+    skip_wait_boot: Optional[bool] = None
+
+@dataclass
+class CreateNewRootVmParams:
+    """If true, wait for the newly-created VM to finish booting before returning. Default: false."""
+    wait_boot: Optional[bool] = None
+
+@dataclass
+class VmLogsParams:
+    """Byte offset into the log file (default: 0)"""
+    offset: Optional[int] = None
+    """Maximum number of log entries to return"""
+    max_entries: Optional[int] = None
+    """Filter by 'stdout' or 'stderr'"""
+    stream: Optional[str] = None
+
+@dataclass
+class BranchByRefParams:
+    """Number of VMs to branch (optional; default 1)"""
+    count: Optional[int] = None
+
+@dataclass
+class BranchByTagParams:
+    """Number of VMs to branch (optional; default 1)"""
+    count: Optional[int] = None
+
+@dataclass
+class BranchVmParams:
+    """If true, keep VM paused after commit. Only applicable when branching a VM ID."""
+    keep_paused: Optional[bool] = None
+    """If true, immediately return an error if VM is booting instead of waiting. Only applicable when branching a VM ID."""
+    skip_wait_boot: Optional[bool] = None
+    """Number of VMs to branch (optional; default 1)"""
+    count: Optional[int] = None
+
+@dataclass
+class UpdateVmStateParams:
+    """If true, error immediately if the VM is not finished booting. Defaults to false"""
+    skip_wait_boot: Optional[bool] = None
+
+@dataclass
+class DeleteVmParams:
+    """If true, return an error immediately if the VM is still booting. Default: false"""
+    skip_wait_boot: Optional[bool] = None
+
+@dataclass
+class BranchByVmParams:
+    """If true, keep VM paused after commit"""
+    keep_paused: Optional[bool] = None
+    """If true, immediately return an error if VM is booting instead of waiting"""
+    skip_wait_boot: Optional[bool] = None
+    """Number of VMs to branch (optional; default 1)"""
+    count: Optional[int] = None
+
+@dataclass
+class CommitVmParams:
+    """If true, keep VM paused after commit"""
+    keep_paused: Optional[bool] = None
+    """If true, return an error immediately if the VM is still booting. Default: false"""
+    skip_wait_boot: Optional[bool] = None
+
+@dataclass
+class ListDomainsParams:
+    """Filter by VM ID"""
+    vm_id: Optional[str] = None
+
+@dataclass
+class BranchByCommitParams:
+    """Number of VMs to branch (optional; default 1)"""
+    count: Optional[int] = None
+

vers_sdk-0.1.1.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: vers-sdk
+Version: 0.1.1
+Summary: SDK for Orchestrator Control Plane API
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hdresearch/python-sdk
+Project-URL: Repository, https://github.com/hdresearch/python-sdk
+Keywords: vers,sdk,api,vm,orchestration
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24

vers_sdk-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+vers_sdk/__init__.py,sha256=ugY30LkuyG5tchECMvhqHSsvtvoWVncOts2VS1uOlE4,743
+vers_sdk/client.py,sha256=43PcyE5-6wpysExLYh9OTIKUmVVET-xMHDVh_QvuIh4,23419
+vers_sdk/errors.py,sha256=riTyZFMt5rYVA960lODYuKSzym3EfjfSrmMyLXcD2p4,3521
+vers_sdk/models.py,sha256=4JwwAiWbzU7HQtmxxLkHDUKWjD45w7vAEQbdecQPrSs,17565
+vers_sdk-0.1.1.dist-info/METADATA,sha256=9Av1nDxBP34fM4OsCGDX4QqVzWUJ5_-_gDKON38KsAE,345
+vers_sdk-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+vers_sdk-0.1.1.dist-info/top_level.txt,sha256=hE4Q_rjEOx9L3TbgqRzMTH5kz8BsvZU4sVUqmaG8Fh0,9
+vers_sdk-0.1.1.dist-info/RECORD,,

vers_sdk-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vers_sdk-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+vers_sdk