computenexa 0.1.1__py3-none-any.whl

computenexa/__init__.py

@@ -0,0 +1,60 @@
+"""ComputeNexa: private GPUs for your business, from Python.
+
+    from computenexa import Client
+
+    cnx = Client()                                    # reads CNX_API_KEY
+    with cnx.gpu("rtx-4090", app="datascience", hours=2) as machine:
+        print(machine.ssh_command)
+
+Guide: https://app.computenexa.com/help/api · Reference: https://app.computenexa.com/help/api/reference
+"""
+
+__version__ = "0.1.1"
+
+from .client import Client
+from .errors import (
+    APIConnectionError,
+    AuthenticationError,
+    ComputeNexaError,
+    ConflictError,
+    GpuLimitReachedError,
+    InsufficientCreditsError,
+    InvalidRequestError,
+    LaunchFailedError,
+    NoCapacityError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProjectInUseError,
+    RateLimitError,
+    ServerError,
+    WaitTimeoutError,
+)
+from .models import Account, App, Catalog, Gpu, Instance, LedgerEntry, Organization, Project, SshKey
+
+__all__ = [
+    "APIConnectionError",
+    "Account",
+    "App",
+    "AuthenticationError",
+    "Catalog",
+    "Client",
+    "ComputeNexaError",
+    "ConflictError",
+    "Gpu",
+    "GpuLimitReachedError",
+    "Instance",
+    "InsufficientCreditsError",
+    "InvalidRequestError",
+    "LaunchFailedError",
+    "LedgerEntry",
+    "NoCapacityError",
+    "NotFoundError",
+    "Organization",
+    "PermissionDeniedError",
+    "Project",
+    "ProjectInUseError",
+    "RateLimitError",
+    "ServerError",
+    "SshKey",
+    "WaitTimeoutError",
+]

computenexa/client.py

@@ -0,0 +1,235 @@
+"""The ComputeNexa API client."""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+import httpx
+
+from . import __version__
+from .errors import APIConnectionError, ComputeNexaError, NotFoundError, RateLimitError, ServerError, from_response
+from .models import ACTIVE, STARTING, Account, Catalog, Instance, LedgerEntry, Project, SshKey
+
+DEFAULT_BASE_URL = "https://api.computenexa.com/v1"
+READS = ("GET", "HEAD")
+
+
+class Client:
+    """A ComputeNexa API client.
+
+        cnx = Client()                         # reads CNX_API_KEY (and CNX_API_URL) from the environment
+        cnx = Client(api_key="cnxk_...")
+
+    Create keys in the dashboard under API keys. A key acts as the person who created it and spends their team's
+    credits. Look-only keys can read; "launch and stop" keys can also launch, extend and stop.
+    """
+
+    def __init__(self, api_key: str | None = None, *, base_url: str | None = None, timeout: float = 30.0,
+                 max_retries: int = 3, http_client: httpx.Client | None = None):
+        key = api_key or os.environ.get("CNX_API_KEY")
+        if not key:
+            raise ComputeNexaError("No API key: pass api_key=... or set CNX_API_KEY. Create one in the dashboard "
+                                   "under API keys.")
+        if not key.startswith("cnxk_"):
+            raise ComputeNexaError("That isn't a ComputeNexa API key: they start with cnxk_.")
+        self.base_url = (base_url or os.environ.get("CNX_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max_retries
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._headers = {"Authorization": f"Bearer {key}", "User-Agent": f"computenexa-python/{__version__}"}
+
+    def __repr__(self) -> str:  # never the key
+        return f"Client(base_url={self.base_url!r})"
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Client:  # noqa: PYI034 (typing.Self needs Python 3.11; we support 3.9)
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------ HTTP
+
+    def _request(self, method: str, path: str, *, json: Any = None, params: dict | None = None) -> Any:
+        """One API call. Reads are retried on 429, 5xx and connection errors; writes only on 429 (refused before
+        anything happened), so a launch is never sent twice."""
+        attempt = 0
+        while True:
+            try:
+                r = self._http.request(method, f"{self.base_url}{path}", json=json, params=params,
+                                       headers=self._headers)
+            except httpx.HTTPError as e:
+                if method in READS and attempt < self.max_retries:
+                    attempt += 1
+                    self._backoff(attempt)
+                    continue
+                raise APIConnectionError(f"Couldn't reach the ComputeNexa API: {e}") from e
+            if r.status_code < 400:
+                return r.json() if r.content else None
+            try:
+                body = r.json()
+            except ValueError:
+                body = None
+            err = from_response(r.status_code, body)
+            retryable = isinstance(err, RateLimitError) or (isinstance(err, ServerError) and method in READS)
+            if retryable and attempt < self.max_retries:
+                attempt += 1
+                self._backoff(attempt, r.headers.get("retry-after"))
+                continue
+            raise err
+
+    @staticmethod
+    def _backoff(attempt: int, retry_after: str | None = None) -> None:
+        try:
+            wait = float(retry_after) if retry_after else 0.0
+        except ValueError:
+            wait = 0.0
+        time.sleep(max(wait, min(30.0, 0.5 * 2 ** attempt + random.random())))
+
+    # ------------------------------------------------------------------ account
+
+    def account(self) -> Account:
+        """Who this key acts as, their team, its balance and GPU limit."""
+        return Account.from_api(self._request("GET", "/me"))
+
+    def balance_cents(self) -> int:
+        """The team's balance in US cents."""
+        return int(self._request("GET", "/balance")["balance_cents"])
+
+    def ledger(self, limit: int = 50) -> list[LedgerEntry]:
+        """Charges, refunds and top-ups, newest first."""
+        return [LedgerEntry.from_api(e) for e in self._request("GET", "/ledger", params={"limit": limit})]
+
+    # ------------------------------------------------------------------ catalog
+
+    def catalog(self, region: str | None = None) -> Catalog:
+        """GPUs with live prices and stock, and the apps and models they run. `region`: "us" or "ca"."""
+        return Catalog.from_api(self._request("GET", "/catalog", params={"region": region} if region else None))
+
+    def image_contents(self, app: str) -> dict:
+        """What's installed in an app's images: Ubuntu, CUDA, Python and every package with its version."""
+        return self._request("GET", f"/images/{app}")
+
+    # ------------------------------------------------------------------ instances
+
+    def launch(self, gpu: str, *, app: str | None = None, image: str | None = None, minutes: int | None = None,
+               hours: float | None = None, gpu_count: int = 1, region: str = "any", label: str | None = None,
+               model: str | None = None, project: Project | str | None = None) -> Instance:
+        """Launch a GPU. It's charged now for the booked time; unused time is refunded when it stops early, all of
+        it if it can't start.
+
+            cnx.launch("rtx-4090", app="datascience", hours=2, project=proj)
+
+        `app`: "basic", "datascience", "chat", "imagegen", "modelapi" or "voice" (or `image=` an exact image slug).
+        `model`: for apps that take one; left out = the recommended model for this GPU.
+        """
+        if (app is None) == (image is None):
+            raise ValueError("Give exactly one of app=... or image=...")
+        body: dict[str, Any] = {"gpu": gpu, "duration_minutes": _minutes(minutes, hours), "gpu_count": gpu_count,
+                                "region": region}
+        if app is not None:
+            body["image_family"] = app
+        if image is not None:
+            body["image"] = image
+        if label is not None:
+            body["label"] = label
+        if model is not None:
+            body["model"] = model
+        if project is not None:
+            body["project_id"] = project.id if isinstance(project, Project) else str(project)
+        return Instance.from_api(self._request("POST", "/instances", json=body), self)
+
+    def get_instance(self, instance_id: str) -> Instance:
+        return Instance.from_api(self._request("GET", f"/instances/{instance_id}"), self)
+
+    def list_instances(self, *, active: bool | None = None, everyone: bool = False, limit: int = 50) -> list[Instance]:
+        """Your machines, newest first. `active=True` only starting/running ones, `False` only ended ones.
+        `everyone=True`: the whole team's (owners and admins)."""
+        params: dict[str, Any] = {"limit": limit}
+        if active is not None:
+            params["status"] = "active" if active else "ended"
+        if everyone:
+            params["whose"] = "everyone"
+        return [Instance.from_api(d, self) for d in self._request("GET", "/instances", params=params)]
+
+    def extend_instance(self, instance_id: str, *, minutes: int | None = None, hours: float | None = None) -> Instance:
+        return Instance.from_api(self._request("POST", f"/instances/{instance_id}/extend",
+                                               json={"minutes": _minutes(minutes, hours)}), self)
+
+    def stop_instance(self, instance_id: str) -> Instance:
+        """End it now: stop if running, cancel if still starting (full refund). An ended one is returned as is."""
+        current = self.get_instance(instance_id)
+        if current.state == "running":
+            return Instance.from_api(self._request("POST", f"/instances/{instance_id}/stop"), self)
+        if current.state in STARTING:
+            return Instance.from_api(self._request("POST", f"/instances/{instance_id}/cancel"), self)
+        return current
+
+    @contextmanager
+    def gpu(self, gpu: str, *, wait: bool = True, timeout: float = 900, **launch: Any) -> Iterator[Instance]:
+        """Launch a GPU for the length of a `with` block, then stop it, even if your code fails:
+
+            with cnx.gpu("rtx-4090", app="datascience", hours=2) as machine:
+                print(machine.ssh_command)
+                ...                      # your work
+            # stopped here; unused time refunded
+
+        `wait=True` (default) returns once it's running. Other arguments are those of `launch`.
+        """
+        machine = self.launch(gpu, **launch)
+        try:
+            if wait:
+                machine.wait_until_running(timeout=timeout)
+            yield machine
+        finally:
+            try:
+                if machine.refresh().state in ACTIVE:
+                    machine.stop()
+            except NotFoundError:
+                pass
+
+    # ------------------------------------------------------------------ projects
+
+    def list_projects(self) -> list[Project]:
+        return [Project.from_api(p) for p in self._request("GET", "/projects")]
+
+    def create_project(self, name: str) -> Project:
+        """An empty project; launch with `project=` to restore it into ~/work and save it back automatically."""
+        return Project.from_api(self._request("POST", "/projects", json={"name": name}))
+
+    def get_or_create_project(self, name: str) -> Project:
+        for p in self.list_projects():
+            if p.name.lower() == name.lower():
+                return p
+        return self.create_project(name)
+
+    def delete_project(self, project: Project | str) -> None:
+        """Delete a project and all its files (refused while a GPU uses it)."""
+        self._request("DELETE", f"/projects/{project.id if isinstance(project, Project) else project}")
+
+    # ------------------------------------------------------------------ SSH keys
+
+    def list_ssh_keys(self) -> list[SshKey]:
+        return [SshKey.from_api(k) for k in self._request("GET", "/ssh-keys")]
+
+    def add_ssh_key(self, name: str, public_key: str) -> SshKey:
+        """Add a public key (e.g. the contents of ~/.ssh/id_ed25519.pub). Never a private key."""
+        return SshKey.from_api(self._request("POST", "/ssh-keys", json={"name": name, "public_key": public_key}))
+
+    def delete_ssh_key(self, key: SshKey | str) -> None:
+        self._request("DELETE", f"/ssh-keys/{key.id if isinstance(key, SshKey) else key}")
+
+
+def _minutes(minutes: int | None, hours: float | None) -> int:
+    if (minutes is None) == (hours is None):
+        raise ValueError("Give exactly one of minutes=... or hours=...")
+    value = int(minutes) if minutes is not None else round(float(hours) * 60)  # type: ignore[arg-type]
+    if value < 1:
+        raise ValueError("The duration must be at least 1 minute.")
+    return value

computenexa/errors.py

@@ -0,0 +1,102 @@
+"""Errors raised by the ComputeNexa client.
+
+Every refusal from the API carries a stable `code` (e.g. "insufficient_credits"), a `message` that is safe to show
+people, and a `request_id` to quote to support@computenexa.com. Catch `ComputeNexaError` for all of them, or a
+subclass for one kind.
+"""
+
+from __future__ import annotations
+
+
+class ComputeNexaError(Exception):
+    """Base class: any error from the client or the API."""
+
+    def __init__(self, message: str, *, status: int | None = None, code: str | None = None,
+                 request_id: str | None = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        extra = ", ".join(f"{k}={v}" for k, v in (("status", self.status), ("code", self.code),
+                                                    ("request_id", self.request_id)) if v is not None)
+        return f"{self.message} ({extra})" if extra else self.message
+
+
+class AuthenticationError(ComputeNexaError):
+    """401: the API key is missing, mistyped or revoked, or its creator left the team."""
+
+
+class PermissionDeniedError(ComputeNexaError):
+    """403: the key can't do this (a look-only key, or a dashboard-only setting), or the account is suspended."""
+
+
+class InsufficientCreditsError(ComputeNexaError):
+    """402: not enough credits for this launch or extension. Add credits in the dashboard."""
+
+
+class NotFoundError(ComputeNexaError):
+    """404: no such machine, project or key, or not one this key can see."""
+
+
+class ConflictError(ComputeNexaError):
+    """409: the request clashes with the current state (see the subclasses)."""
+
+
+class NoCapacityError(ConflictError):
+    """409 no_capacity: that GPU is fully booked right now. Retry later or pick another GPU."""
+
+
+class GpuLimitReachedError(ConflictError):
+    """409 gpu_limit_reached: your team (or you) already run as many GPUs as allowed."""
+
+
+class ProjectInUseError(ConflictError):
+    """409 project_in_use: another GPU is using this project."""
+
+
+class InvalidRequestError(ComputeNexaError):
+    """422: a field is missing or wrong; the message says which."""
+
+
+class RateLimitError(ComputeNexaError):
+    """429: more than 120 requests a minute with this key. The client retries these by itself first."""
+
+
+class ServerError(ComputeNexaError):
+    """5xx: something went wrong on our side. The client retries these by itself first."""
+
+
+class APIConnectionError(ComputeNexaError):
+    """The API couldn't be reached (network, DNS, timeout)."""
+
+
+class LaunchFailedError(ComputeNexaError):
+    """The machine couldn't start (no capacity after all, timeout…). Its cost was refunded in full."""
+
+
+class WaitTimeoutError(ComputeNexaError):
+    """`wait_until_running` gave up before the machine was ready. The machine may still start: check or stop it."""
+
+
+_BY_CODE = {
+    "no_capacity": NoCapacityError,
+    "gpu_limit_reached": GpuLimitReachedError,
+    "project_in_use": ProjectInUseError,
+    "insufficient_credits": InsufficientCreditsError,
+}
+_BY_STATUS = {401: AuthenticationError, 402: InsufficientCreditsError, 403: PermissionDeniedError,
+              404: NotFoundError, 409: ConflictError, 422: InvalidRequestError, 429: RateLimitError}
+
+
+def from_response(status: int, body: object) -> ComputeNexaError:
+    """The error for an API refusal: by its code first, else by its HTTP status."""
+    data = body if isinstance(body, dict) else {}
+    code = data.get("error") if isinstance(data.get("error"), str) else None
+    message = data.get("message") or data.get("detail") or f"HTTP {status}"
+    if not isinstance(message, str):
+        message = str(message)
+    cls = _BY_CODE.get(code or "") or _BY_STATUS.get(status) or (ServerError if status >= 500 else ComputeNexaError)
+    return cls(message, status=status, code=code, request_id=data.get("request_id"))

computenexa/models.py

@@ -0,0 +1,261 @@
+"""What the API returns, as Python objects. Every object keeps the full reply in `.raw` (fields added to the API
+later are there before this library knows them)."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from .errors import LaunchFailedError, WaitTimeoutError
+
+if TYPE_CHECKING:
+    from .client import Client
+
+STARTING = ("requested", "provisioning")
+ACTIVE = ("requested", "provisioning", "running")
+ENDED = ("terminated", "failed")
+
+
+def _time(value: Any) -> datetime | None:
+    if not value:
+        return None
+    return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+
+
+@dataclass
+class Organization:
+    id: str
+    name: str
+    role: str        # your role in it: owner | admin | member
+    members: int
+
+
+@dataclass
+class Account:
+    """Who the API key acts as, and their team."""
+
+    id: str
+    email: str
+    balance_cents: int          # the team's balance
+    max_concurrent_gpus: int    # the team's GPU limit
+    organization: Organization
+    raw: dict = field(repr=False)
+
+    @property
+    def balance(self) -> float:
+        """The team's balance in US dollars."""
+        return self.balance_cents / 100
+
+    @classmethod
+    def from_api(cls, d: dict) -> Account:
+        o = d.get("organization") or {}
+        return cls(id=d["id"], email=d["email"], balance_cents=d["balance_cents"],
+                   max_concurrent_gpus=d["max_concurrent_gpus"],
+                   organization=Organization(id=o.get("id", ""), name=o.get("name", ""), role=o.get("role", ""),
+                                             members=o.get("members", 1)), raw=d)
+
+
+@dataclass
+class Gpu:
+    """A GPU in the catalog."""
+
+    slug: str                   # what you launch with, e.g. "rtx-4090"
+    name: str                   # e.g. "NVIDIA RTX 4090"
+    vram_gb: int
+    available: bool
+    price_per_hour_cents: int | None   # None when not for sale right now
+    billing_unit: str           # "minute", or "hour" (billed per started hour)
+    apps: list[str]             # apps (image families) it runs: "chat", "datascience", …
+    regions: list[str]
+    raw: dict = field(repr=False)
+
+    @classmethod
+    def from_api(cls, d: dict) -> Gpu:
+        return cls(slug=d["slug"], name=d["display_name"], vram_gb=d["vram_gb"], available=d["available"],
+                   price_per_hour_cents=d.get("price_per_hour_cents"), billing_unit=d.get("billing_unit", "minute"),
+                   apps=sorted((d.get("families") or {}).keys()), regions=list(d.get("regions") or []), raw=d)
+
+
+@dataclass
+class App:
+    """Something a GPU can start with (an image family): "basic", "datascience", "chat", "imagegen", "modelapi",
+    "voice"."""
+
+    name: str                   # the value for `app=` / image_family
+    display_name: str           # as on the launch page
+    summary: str
+    needs_ssh_key: bool
+    models: list[dict]          # models offered (chat, imagegen, modelapi, voice); [] for the others
+    model_required: bool
+    recommended: list[tuple[int, str]]  # [(min GPU memory in GB, model)], first match wins
+
+    def recommended_model(self, vram_gb: int) -> str | None:
+        """Our pick for a GPU with this much memory, or None."""
+        return next((m for min_gb, m in self.recommended if vram_gb >= min_gb), None)
+
+
+@dataclass
+class Catalog:
+    region: str
+    gpus: list[Gpu]
+    apps: dict[str, App]
+    raw: dict = field(repr=False)
+
+    def gpu(self, slug: str) -> Gpu:
+        for g in self.gpus:
+            if g.slug == slug:
+                return g
+        raise KeyError(f"no GPU {slug!r} in the catalog; known: {', '.join(g.slug for g in self.gpus)}")
+
+    def available(self, app: str | None = None) -> list[Gpu]:
+        """GPUs for sale right now, cheapest first; only those that run `app` if given."""
+        found = [g for g in self.gpus if g.available and g.price_per_hour_cents is not None
+                 and (app is None or app in g.apps)]
+        return sorted(found, key=lambda g: g.price_per_hour_cents or 0)
+
+    @classmethod
+    def from_api(cls, d: dict) -> Catalog:
+        models = d.get("launch_models") or {}
+        apps = {}
+        for f in d.get("families") or []:
+            m = models.get(f["family"]) or {}
+            apps[f["family"]] = App(
+                name=f["family"], display_name=f.get("display_name", f["family"]), summary=f.get("summary", ""),
+                needs_ssh_key=f.get("needs_ssh_key", True), models=list(m.get("models") or []),
+                model_required=bool(m.get("required")),
+                recommended=[(int(a), str(b)) for a, b in m.get("recommended") or []])
+        return cls(region=d.get("region", "any"), gpus=[Gpu.from_api(g) for g in d.get("gpus") or []], apps=apps,
+                   raw=d)
+
+
+@dataclass
+class Project:
+    """Saved storage: restored into ~/work on GPUs launched with it, and saved back automatically."""
+
+    id: str
+    name: str
+    bytes_used: int
+    files: int
+    created_at: datetime | None
+    last_used_at: datetime | None
+    in_use_by: str | None       # the machine using it right now, if any
+    raw: dict = field(repr=False)
+
+    @classmethod
+    def from_api(cls, d: dict) -> Project:
+        return cls(id=d["id"], name=d["name"], bytes_used=d.get("bytes_used", 0), files=d.get("files", 0),
+                   created_at=_time(d.get("created_at")), last_used_at=_time(d.get("last_used_at")),
+                   in_use_by=d.get("in_use_by"), raw=d)
+
+
+@dataclass
+class SshKey:
+    id: str
+    name: str
+    fingerprint: str
+    raw: dict = field(repr=False)
+
+    @classmethod
+    def from_api(cls, d: dict) -> SshKey:
+        return cls(id=str(d["id"]), name=d["name"], fingerprint=d.get("fingerprint", ""), raw=d)
+
+
+@dataclass
+class LedgerEntry:
+    created_at: datetime | None
+    kind: str                   # topup | charge | refund | adjustment
+    amount_cents: int           # + credit, − debit
+    description: str
+    instance: str | None
+    raw: dict = field(repr=False)
+
+    @classmethod
+    def from_api(cls, d: dict) -> LedgerEntry:
+        return cls(created_at=_time(d.get("created_at")), kind=d["kind"], amount_cents=d["amount_cents"],
+                   description=d.get("description", ""), instance=d.get("instance"), raw=d)
+
+
+@dataclass
+class Instance:
+    """A GPU machine. Methods act on it through the client that returned it."""
+
+    id: str                     # e.g. "cnx-7f3a9c"
+    state: str                  # requested | provisioning | running | stopping | terminated | failed
+    gpu: str
+    gpu_count: int
+    app: str                    # its image family
+    label: str | None
+    price_per_hour_cents: int
+    ssh_command: str | None     # while running, if you have an SSH key
+    expires_at: datetime | None
+    time_left_seconds: int | None
+    charged_cents: int
+    refunded_cents: int
+    cost_so_far_cents: int
+    end_reason: str | None
+    startup_progress: str | None
+    raw: dict = field(repr=False)
+    _client: Client | None = field(default=None, repr=False, compare=False)
+
+    @property
+    def is_running(self) -> bool:
+        return self.state == "running"
+
+    @property
+    def is_active(self) -> bool:
+        """Starting or running: it may still cost money."""
+        return self.state in ACTIVE
+
+    @classmethod
+    def from_api(cls, d: dict, client: Client | None = None) -> Instance:
+        return cls(id=d["id"], state=d["state"], gpu=d["gpu"], gpu_count=d.get("gpu_count", 1),
+                   app=d.get("image_family", ""), label=d.get("label"),
+                   price_per_hour_cents=d.get("price_per_hour_cents", 0), ssh_command=d.get("ssh_command"),
+                   expires_at=_time(d.get("expires_at")), time_left_seconds=d.get("time_left_seconds"),
+                   charged_cents=d.get("charged_cents", 0), refunded_cents=d.get("refunded_cents", 0),
+                   cost_so_far_cents=d.get("cost_so_far_cents", 0), end_reason=d.get("end_reason"),
+                   startup_progress=d.get("startup_progress"), raw=d, _client=client)
+
+    def _update(self, other: Instance) -> Instance:
+        for name in self.__dataclass_fields__:
+            if name != "_client":
+                setattr(self, name, getattr(other, name))
+        return self
+
+    def _c(self) -> Client:
+        if self._client is None:
+            raise RuntimeError("this Instance isn't attached to a client")
+        return self._client
+
+    def refresh(self) -> Instance:
+        """Fetch its current state (in place; returns itself)."""
+        return self._update(self._c().get_instance(self.id))
+
+    def wait_until_running(self, timeout: float = 900, poll: float = 10,
+                           on_progress: Any = None) -> Instance:
+        """Wait until it's running. Raises LaunchFailedError if it couldn't start (refunded in full), or
+        WaitTimeoutError after `timeout` seconds (it may still start: check or stop it). `on_progress(instance)` is
+        called after each check, e.g. to print `instance.startup_progress`."""
+        deadline = time.monotonic() + timeout
+        while True:
+            self.refresh()
+            if on_progress is not None:
+                on_progress(self)
+            if self.state == "running":
+                return self
+            if self.state not in STARTING:
+                raise LaunchFailedError(f"{self.id} didn't start: {self.state}"
+                                        + (f" ({self.end_reason})" if self.end_reason else ""))
+            if time.monotonic() >= deadline:
+                raise WaitTimeoutError(f"{self.id} wasn't running after {timeout:.0f} s (still {self.state})")
+            time.sleep(poll)
+
+    def extend(self, minutes: int | None = None, *, hours: float | None = None) -> Instance:
+        """Add time at the price it launched with."""
+        return self._update(self._c().extend_instance(self.id, minutes=minutes, hours=hours))
+
+    def stop(self) -> Instance:
+        """End it now: stop if running, cancel if still starting. Unused time is refunded."""
+        return self._update(self._c().stop_instance(self.id))

computenexa-0.1.1.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: computenexa
+Version: 0.1.1
+Summary: Python client for ComputeNexa: private GPUs for your business, launched and stopped from code.
+Project-URL: Homepage, https://computenexa.com
+Project-URL: Documentation, https://app.computenexa.com/help/api
+Project-URL: API reference, https://app.computenexa.com/help/api/reference
+Project-URL: Support, https://app.computenexa.com/help
+Author-email: ComputeNexa <support@computenexa.com>
+Maintainer-email: ComputeNexa <support@computenexa.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cloud,computenexa,gpu,inference,llm,private ai,training
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# ComputeNexa Python SDK
+
+Launch, use and stop private GPUs on [ComputeNexa](https://computenexa.com) from Python. Each GPU is reserved for
+your team, runs open AI models or your own code, and is paid by the minute from your team's prepaid credits.
+
+```bash
+pip install computenexa
+```
+
+## Quick start
+
+Create an API key in the dashboard under **API keys** ("Launch and stop" to launch), then:
+
+```bash
+export CNX_API_KEY="cnxk_..."
+```
+
+```python
+from computenexa import Client
+
+cnx = Client()                                    # reads CNX_API_KEY
+
+# Launch an RTX 4090 with JupyterLab and PyTorch for 2 hours; it's stopped when the block ends,
+# even if your code fails, and unused minutes are refunded.
+with cnx.gpu("rtx-4090", app="datascience", hours=2) as machine:
+    print(machine.ssh_command)                    # ssh cnx-7f3a9c@ssh.computenexa.com
+    ...                                           # your work
+```
+
+## Choose a GPU and an app
+
+```python
+catalog = cnx.catalog()                           # live prices and stock; catalog.apps describes each app
+for gpu in catalog.available(app="chat"):         # for sale now, cheapest first
+    print(gpu.slug, gpu.vram_gb, "GB", gpu.price_per_hour_cents / 100, "$/h")
+
+chat = catalog.apps["chat"]
+print(chat.recommended_model(vram_gb=48))         # our model pick for a 48 GB GPU
+print(cnx.image_contents("datascience"))          # every package and version installed
+```
+
+| `app=` | On the launch page | For |
+|---|---|---|
+| `chat` | Private Chat | chat with open AI models about your documents, in your browser |
+| `imagegen` | Image Generation (ComfyUI) | images with SDXL or FLUX |
+| `modelapi` | Model API (vLLM) | an AI model behind your own API key |
+| `voice` | Voice Agent | speech in, spoken AI reply out |
+| `datascience` | Notebook (Jupyter) | JupyterLab, PyTorch, pandas: analysis, training, fine-tuning |
+| `basic` | Basic (SSH only) | Ubuntu + CUDA for your own code |
+
+## Keep files between sessions with projects
+
+A project is saved storage: launched with it, a GPU starts with the project's files in `~/work` and saves
+`~/work` back automatically.
+
+```python
+project = cnx.get_or_create_project("titanic-training")
+machine = cnx.launch("l40s", app="datascience", hours=4, project=project, label="nightly training")
+machine.wait_until_running(on_progress=lambda m: print(m.state, m.startup_progress or ""))
+print(machine.ssh_command)
+# ... later
+machine.stop()
+print("refunded", machine.refunded_cents / 100)
+```
+
+## Machines
+
+```python
+cnx.list_instances(active=True)                   # your running and starting machines
+cnx.list_instances(everyone=True)                 # the whole team's (owners and admins)
+machine = cnx.get_instance("cnx-7f3a9c")
+machine.extend(hours=1)                           # same price it launched with
+machine.stop()                                    # stops if running, cancels if still starting
+```
+
+## Account, credits and SSH keys
+
+```python
+me = cnx.account()
+print(me.email, me.organization.name, me.organization.role, me.balance, me.max_concurrent_gpus)
+for entry in cnx.ledger(limit=20):
+    print(entry.created_at, entry.description, entry.amount_cents / 100)
+
+cnx.add_ssh_key("Work laptop", open("/Users/me/.ssh/id_ed25519.pub").read())   # the PUBLIC key only
+```
+
+## Errors
+
+Every refusal raises a subclass of `computenexa.ComputeNexaError` with a stable `code`, a `message` you can show
+and a `request_id` to quote to support:
+
+| Exception | When |
+|---|---|
+| `InsufficientCreditsError` | not enough credits for the launch or extension |
+| `NoCapacityError` | that GPU is fully booked right now: retry or pick another |
+| `GpuLimitReachedError` | your team (or you) already run as many GPUs as allowed |
+| `ProjectInUseError` | another GPU is using the project |
+| `AuthenticationError` | the key is missing, mistyped or revoked |
+| `PermissionDeniedError` | a look-only key tried to launch, or a dashboard-only setting |
+| `NotFoundError` | no such machine or project, or not one you can see |
+| `LaunchFailedError` | the machine couldn't start (refunded in full) |
+| `WaitTimeoutError` | `wait_until_running` gave up; the machine may still start |
+
+```python
+from computenexa import NoCapacityError
+
+for gpu in ["rtx-4090", "l40s", "a40"]:
+    try:
+        machine = cnx.launch(gpu, app="chat", hours=1)
+        break
+    except NoCapacityError:
+        continue
+```
+
+Reads are retried automatically when the API is busy (429) or has a server error. A launch is never retried after
+an uncertain failure, so it can't start two GPUs.
+
+## Configuration
+
+| | |
+|---|---|
+| `Client(api_key=...)` or `CNX_API_KEY` | your API key |
+| `Client(base_url=...)` or `CNX_API_URL` | defaults to `https://api.computenexa.com/v1` |
+| `Client(timeout=30, max_retries=3)` | per request |
+
+## Help
+
+- Guide: <https://app.computenexa.com/help/api>
+- Every operation: <https://app.computenexa.com/help/api/reference>
+- Support: <support@computenexa.com>
+
+MIT licensed. © ComputeNexa.

computenexa-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+computenexa/__init__.py,sha256=-WAmlRie2He7fbuGG-HL6aujKvR5wq_FR-sY936uYME,1443
+computenexa/client.py,sha256=UHt77B2giIFE6dQt_AHa1gDzRM5RaAzGzB_Kmgbug1Y,11158
+computenexa/errors.py,sha256=R33ILaz0lJSQAiBzTuDrnuaEHjHZfiHUaF_s8-24fbo,3921
+computenexa/models.py,sha256=Ee0JUC27YyTU5Uwj4LBjO_7SiMqxqxvTWPJvLEmkLYw,10148
+computenexa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+computenexa-0.1.1.dist-info/METADATA,sha256=c5dpLekLj1wROqWX4JgIy0wGFVvmfD5FUSQ_OCLJf_A,5992
+computenexa-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+computenexa-0.1.1.dist-info/licenses/LICENSE,sha256=2QFwVb5OF20CkVUdITA4oVlgRJFDfLGpSr7UjCAxV1s,1068
+computenexa-0.1.1.dist-info/RECORD,,

computenexa-0.1.1.dist-info/WHEEL

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

computenexa-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ComputeNexa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.