everpod 0.1.0__py3-none-any.whl

everpod/__init__.py

@@ -0,0 +1,43 @@
+"""Everpod — Household AI Infrastructure.
+
+    from everpod import Everpod
+
+    client = Everpod(api_key="evp_...")
+    image = client.images.generate(prompt="a lighthouse at dusk")
+    image.save("lighthouse.png")
+
+Generation is a *job* on a real GPU in a real home, so it is asynchronous by
+nature. ``generate()`` hides that by polling to completion; use
+``images.submit()`` when you want the job id back immediately.
+"""
+
+from __future__ import annotations
+
+from everpod.client import Everpod
+from everpod.errors import (
+    EverpodError,
+    JobFailedError,
+    NoCapacityError,
+    RateLimitError,
+    TimeoutError,
+    UnauthorizedError,
+)
+from everpod.models import Artifact, Image, Job, Model, Usage
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Artifact",
+    "Everpod",
+    "EverpodError",
+    "Image",
+    "Job",
+    "JobFailedError",
+    "Model",
+    "NoCapacityError",
+    "RateLimitError",
+    "TimeoutError",
+    "UnauthorizedError",
+    "Usage",
+    "__version__",
+]

everpod/client.py

@@ -0,0 +1,202 @@
+"""The Everpod client."""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+import httpx
+
+from everpod.errors import (
+    EverpodError,
+    JobFailedError,
+    NoCapacityError,
+    RateLimitError,
+    TimeoutError,
+    UnauthorizedError,
+)
+from everpod.models import Image, Job, Model, Usage
+
+DEFAULT_BASE_URL = "https://api.everpod.io"
+
+
+class Everpod:
+    """Client for the Everpod API.
+
+    ``api_key`` falls back to the ``EVERPOD_API_KEY`` environment variable, so
+    scripts and notebooks need no literal key in source.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        key = api_key or os.environ.get("EVERPOD_API_KEY")
+        if not key:
+            raise UnauthorizedError(
+                "no API key: pass api_key=... or set EVERPOD_API_KEY "
+                "(create one at https://app.everpod.io/keys/)"
+            )
+        self._base_url = (base_url or os.environ.get("EVERPOD_BASE_URL") or DEFAULT_BASE_URL).rstrip(
+            "/"
+        )
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {key}",
+                "User-Agent": "everpod-python/0.1.0",
+            },
+        )
+        self.images = _Images(self)
+        self.jobs = _Jobs(self)
+        self.models = _Models(self)
+        self.usage = _Usage(self)
+
+    # ------------------------------------------------------------- transport
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.HTTPError as exc:
+            raise EverpodError(f"network error talking to {self._base_url}: {exc}") from exc
+
+        if response.status_code in (401, 403):
+            raise UnauthorizedError("API key rejected — is it revoked? (see /keys)")
+        if response.status_code == 429:
+            raise RateLimitError("rate limited — slow down and retry")
+        if response.status_code >= 400:
+            detail = ""
+            try:
+                detail = response.json().get("detail", "")
+            except Exception:  # noqa: BLE001 - body may not be JSON
+                detail = response.text[:200]
+            raise EverpodError(f"{method} {path} -> {response.status_code}: {detail}")
+        result: dict[str, Any] = response.json() if response.content else {}
+        return result
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Everpod:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class _Images:
+    def __init__(self, client: Everpod) -> None:
+        self._c = client
+
+    def submit(
+        self,
+        *,
+        prompt: str,
+        model: str = "z-image-turbo",
+        size: str | None = None,
+        seed: int | None = None,
+        idempotency_key: str | None = None,
+    ) -> Job:
+        """Queue a generation and return immediately."""
+        body: dict[str, Any] = {"prompt": prompt, "model": model}
+        if size:
+            body["size"] = size
+        if seed is not None:
+            body["seed"] = seed
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        raw = self._c._request("POST", "/v1/images/generations", json=body, headers=headers)
+        return Job._from_api(raw)
+
+    def generate(
+        self,
+        *,
+        prompt: str,
+        model: str = "z-image-turbo",
+        size: str | None = None,
+        seed: int | None = None,
+        timeout: float = 600.0,
+        poll_interval: float = 1.5,
+        idempotency_key: str | None = None,
+    ) -> Image:
+        """Queue a generation and block until it finishes.
+
+        Raises :class:`JobFailedError` if it ends badly and
+        :class:`TimeoutError` if ``timeout`` elapses first (the job keeps
+        running server-side either way).
+        """
+        job = self.submit(
+            prompt=prompt,
+            model=model,
+            size=size,
+            seed=seed,
+            idempotency_key=idempotency_key,
+        )
+        finished = self._c.jobs.wait(job.id, timeout=timeout, poll_interval=poll_interval)
+        if not finished.succeeded:
+            raise JobFailedError(finished.id, finished.status, finished.failure_reason)
+        if not finished.artifacts:
+            raise EverpodError(f"job {finished.id} succeeded with no artifact")
+        return Image(job=finished)
+
+
+class _Jobs:
+    def __init__(self, client: Everpod) -> None:
+        self._c = client
+
+    def retrieve(self, job_id: str) -> Job:
+        return Job._from_api(self._c._request("GET", f"/v1/jobs/{job_id}"))
+
+    def cancel(self, job_id: str) -> Job:
+        return Job._from_api(self._c._request("POST", f"/v1/jobs/{job_id}/cancel"))
+
+    def wait(self, job_id: str, *, timeout: float = 600.0, poll_interval: float = 1.5) -> Job:
+        """Poll until the job is terminal."""
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.retrieve(job_id)
+            if job.done:
+                return job
+            if time.monotonic() >= deadline:
+                raise TimeoutError(job_id, timeout)
+            time.sleep(poll_interval)
+
+
+class _Models:
+    def __init__(self, client: Everpod) -> None:
+        self._c = client
+
+    def list(self) -> list[Model]:
+        """Every catalog model, with LIVE capacity.
+
+        ``available`` is False when no online node can currently serve it —
+        check it before submitting rather than queueing into nothing.
+        """
+        raw = self._c._client.get("/v1/models").json()
+        return [Model._from_api(m) for m in raw]
+
+    def available(self) -> list[Model]:
+        return [m for m in self.list() if m.available]
+
+    def require(self, name: str) -> Model:
+        """Return the model, or raise :class:`NoCapacityError` if it cannot run now."""
+        for model in self.list():
+            if model.name == name:
+                if not model.available:
+                    raise NoCapacityError(f"no node is serving {name!r} right now")
+                return model
+        raise EverpodError(f"unknown model {name!r}")
+
+
+class _Usage:
+    def __init__(self, client: Everpod) -> None:
+        self._c = client
+
+    def get(self, *, days: int = 30, limit: int = 50) -> Usage:
+        """Your metered usage: totals, per-day, per-model, and recent executions."""
+        return Usage._from_api(
+            self._c._request("GET", "/v1/usage", params={"days": days, "limit": limit})
+        )

everpod/errors.py

@@ -0,0 +1,49 @@
+"""Typed errors — every failure mode a caller can reasonably branch on."""
+
+from __future__ import annotations
+
+
+class EverpodError(Exception):
+    """Base class for everything this library raises."""
+
+
+class UnauthorizedError(EverpodError):
+    """The API key is missing, wrong, or revoked."""
+
+
+class RateLimitError(EverpodError):
+    """Too many requests; retry after a pause."""
+
+
+class NoCapacityError(EverpodError):
+    """No node can serve this model right now.
+
+    Distinct from a failure: the request was valid, the fleet is just busy or
+    the model is not resident on any online node. Retry later, or call
+    ``client.models.list()`` and pick one that reports ``available``.
+    """
+
+
+class JobFailedError(EverpodError):
+    """The job reached a terminal non-success state."""
+
+    def __init__(self, job_id: str, status: str, reason: str | None = None) -> None:
+        self.job_id = job_id
+        self.status = status
+        self.reason = reason
+        super().__init__(f"job {job_id} {status.lower()}" + (f": {reason}" if reason else ""))
+
+
+class TimeoutError(EverpodError):  # noqa: A001 - deliberate, mirrors the builtin name
+    """The job did not finish within the requested timeout.
+
+    The job keeps running — poll ``client.jobs.retrieve(job_id)`` later.
+    """
+
+    def __init__(self, job_id: str, waited: float) -> None:
+        self.job_id = job_id
+        self.waited = waited
+        super().__init__(
+            f"job {job_id} still running after {waited:.0f}s "
+            f"(it has not been cancelled — poll jobs.retrieve to keep waiting)"
+        )

everpod/models.py

@@ -0,0 +1,133 @@
+"""Plain dataclasses for what the API returns. No pydantic dependency."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+
+@dataclass(frozen=True)
+class Artifact:
+    url: str
+    content_type: str
+    bytes: int
+    width: int | None = None
+    height: int | None = None
+
+    def read(self, *, timeout: float = 60.0) -> bytes:
+        """Download the artifact bytes."""
+        response = httpx.get(self.url, timeout=timeout, follow_redirects=True)
+        response.raise_for_status()
+        return response.content
+
+    def save(self, path: str | Path, *, timeout: float = 60.0) -> Path:
+        """Download and write to ``path``. Returns the path."""
+        out = Path(path)
+        out.write_bytes(self.read(timeout=timeout))
+        return out
+
+    @classmethod
+    def _from_api(cls, raw: dict[str, Any]) -> Artifact:
+        return cls(
+            url=raw["url"],
+            content_type=raw.get("content_type", "application/octet-stream"),
+            bytes=int(raw.get("bytes", 0)),
+            width=raw.get("width"),
+            height=raw.get("height"),
+        )
+
+
+@dataclass(frozen=True)
+class Job:
+    id: str
+    status: str
+    model: str
+    progress: float | None = None
+    failure_reason: str | None = None
+    artifacts: list[Artifact] = field(default_factory=list)
+
+    #: Statuses from which a job will never move again.
+    TERMINAL = frozenset({"SUCCEEDED", "PERMANENT_FAILED", "UNCERTAIN", "CANCELLED"})
+
+    @property
+    def done(self) -> bool:
+        return self.status in self.TERMINAL
+
+    @property
+    def succeeded(self) -> bool:
+        return self.status == "SUCCEEDED"
+
+    @classmethod
+    def _from_api(cls, raw: dict[str, Any]) -> Job:
+        return cls(
+            id=raw["job_id"],
+            status=raw["status"],
+            model=raw.get("model", ""),
+            progress=raw.get("progress"),
+            failure_reason=raw.get("failure_reason"),
+            artifacts=[Artifact._from_api(a) for a in raw.get("artifacts") or []],
+        )
+
+
+@dataclass(frozen=True)
+class Image:
+    """A finished generation: the job plus its first artifact."""
+
+    job: Job
+
+    @property
+    def url(self) -> str:
+        return self.job.artifacts[0].url
+
+    @property
+    def artifact(self) -> Artifact:
+        return self.job.artifacts[0]
+
+    def read(self, *, timeout: float = 60.0) -> bytes:
+        return self.artifact.read(timeout=timeout)
+
+    def save(self, path: str | Path, *, timeout: float = 60.0) -> Path:
+        return self.artifact.save(path, timeout=timeout)
+
+
+@dataclass(frozen=True)
+class Model:
+    name: str
+    job_type: str
+    quantization: str
+    ready_workers: int
+    available: bool
+
+    @classmethod
+    def _from_api(cls, raw: dict[str, Any]) -> Model:
+        return cls(
+            name=raw["model"],
+            job_type=raw.get("job_type", "IMAGE"),
+            quantization=raw.get("quantization", ""),
+            ready_workers=int(raw.get("ready_workers", 0)),
+            available=bool(raw.get("available")),
+        )
+
+
+@dataclass(frozen=True)
+class Usage:
+    window_days: int
+    total_jobs: int
+    total_gpu_seconds: float
+    by_day: list[dict[str, Any]]
+    by_model: list[dict[str, Any]]
+    recent: list[dict[str, Any]]
+
+    @classmethod
+    def _from_api(cls, raw: dict[str, Any]) -> Usage:
+        return cls(
+            window_days=int(raw.get("window_days", 0)),
+            total_jobs=int(raw.get("total_jobs", 0)),
+            total_gpu_seconds=float(raw.get("total_gpu_seconds", 0.0)),
+            by_day=raw.get("by_day") or [],
+            by_model=raw.get("by_model") or [],
+            recent=raw.get("recent") or [],
+        )

everpod-0.1.0.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: everpod
+Version: 0.1.0
+Summary: Python client for Everpod — GPU inference on Household AI Infrastructure
+Project-URL: Homepage, https://everpod.io
+Project-URL: Documentation, https://api.everpod.io/docs
+Project-URL: Console, https://app.everpod.io
+Author-email: Everpod <support@everpod.io>
+License: Apache-2.0
+Keywords: ai,everpod,gpu,image-generation,inference
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# everpod
+
+Python client for [Everpod](https://everpod.io) — GPU inference on Household AI Infrastructure.
+
+```bash
+pip install everpod
+```
+
+```python
+from everpod import Everpod
+
+client = Everpod(api_key="evp_...")  # or set EVERPOD_API_KEY
+
+image = client.images.generate(prompt="a lighthouse at dusk, cinematic")
+image.save("lighthouse.png")
+```
+
+Generation runs as a **job** on a real GPU node; `generate()` polls to
+completion for you. For async control:
+
+```python
+job = client.images.submit(prompt="a lighthouse at dusk")
+job = client.jobs.wait(job.id, timeout=120)
+print(job.artifacts[0].url)
+```
+
+Check live capacity before submitting — models are only offered while a node
+can serve them:
+
+```python
+for model in client.models.available():
+    print(model.name, model.ready_workers)
+```
+
+Your metered usage (nothing is billed during the pilot):
+
+```python
+usage = client.usage.get(days=30)
+print(usage.total_jobs, usage.total_gpu_seconds)
+for row in usage.recent:
+    print(row["job_id"], row["gpu_seconds"])
+```
+
+Get an API key at [app.everpod.io/keys](https://app.everpod.io/keys/) ·
+API reference at [api.everpod.io/docs](https://api.everpod.io/docs).

everpod-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+everpod/__init__.py,sha256=xSBXApThCdJqeT4zlXAKluR0dmdBwPi6MuexB7LstRc,981
+everpod/client.py,sha256=Pn-1SJUMsVcTW1pl3M_KmzmSPMWg8eEIzJjkACNIBx4,6698
+everpod/errors.py,sha256=1DxWI33ceoXVbwfA3jB4P9_YF9dJBjlcuqGOOx5brqM,1594
+everpod/models.py,sha256=OOp3-lrxZRGe_-SpW4lVMDV_0dnWKYr9plh4hs6YaEA,3728
+everpod-0.1.0.dist-info/METADATA,sha256=1bAjFj9XRmezLk9XMM_W7xrP25WNEfZXZIv5KPvgXDI,1924
+everpod-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+everpod-0.1.0.dist-info/RECORD,,

everpod-0.1.0.dist-info/WHEEL

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