ppio-gpus 0.0.1__tar.gz

ppio_gpus-0.0.1/.gitignore

@@ -0,0 +1,56 @@
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+go.work.sum
+
+# env file
+.env
+vendor/
+
+# controller-gen
+bin/
+
+.stfolder
+.stignore
+.idea/
+pkg/mod/
+pkg/sumdb/
+
+cmd/autoscaler/autoscaler
+cmd/datawatcher/datawatcher
+cmd/gateway/gateway
+cmd/monolithic-gateway/gateway
+cmd/taskproxy/taskproxy
+cmd/taskscheduler/taskscheduler
+cmd/metricserver/metricserver
+deploy/nitor-*.tgz
+deploy/manifests.yaml
+
+main
+*.pkl
+*.pkl.lock
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.venv/

ppio_gpus-0.0.1/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: ppio-gpus
+Version: 0.0.1
+Summary: PPIO GPUs SDK - Python SDK for PPIO serverless GPU endpoints
+Project-URL: Homepage, https://ppio.com/
+Author-email: PPIO <support@ppio.com>
+License: MIT
+Keywords: ai,gpu,inference,ppio,sdk,serverless
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: aiohttp-retry>=2.8.3
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: boto3>=1.28.0
+Requires-Dist: filelock>=3.12.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: urllib3>=2.0.0
+Description-Content-Type: text/markdown
+
+# ppio-gpus
+
+Python SDK for PPIO serverless GPU endpoints.
+
+## Installation
+
+```bash
+pip install ppio-gpus
+```
+
+## Quick Start (Client)
+
+```python
+import ppio_gpus
+
+ppio_gpus.api_key = "your-api-key"
+
+endpoint = ppio_gpus.Endpoint("your-endpoint-id")
+job = endpoint.run({"prompt": "hello world"})
+
+print(job.status())
+output = job.output(timeout=60)
+print(output)
+```
+
+## Quick Start (Worker)
+
+```python
+import ppio_gpus
+
+def handler(job):
+    job_input = job["input"]
+    # ... process ...
+    return {"result": "done"}
+
+ppio_gpus.start({"handler": handler})
+```
+
+## Client API
+
+- `Endpoint(endpoint_id)` -- create an endpoint client
+- `Endpoint.run(input)` -- async submit a task, returns a `Job` immediately
+- `Endpoint.health()` -- check endpoint health
+- `Endpoint.purge_queue()` -- cancel all pending tasks
+- `Job.status()` -- get current task status
+- `Job.output(timeout=0)` -- get task output, optionally poll until complete
+- `Job.cancel()` -- cancel a running task
+
+## Worker API
+
+- `ppio_gpus.start(config)` -- start the worker loop (blocks until SIGTERM)
+- `ppio_gpus.progress_update(job, data)` -- send in-progress status update
+- `ppio_gpus.upload_image(job_id, path)` -- upload image to S3, returns presigned URL
+- `ppio_gpus.upload_file(name, path)` -- upload file to S3
+- `ppio_gpus.upload_bytes(name, data)` -- upload bytes to S3
+
+## Configuration
+
+Set credentials via environment variables:
+
+```bash
+export PPIO_API_KEY="your-api-key"
+export PPIO_ENDPOINT_BASE_URL="https://async-public.serverless.ppinfra.com/v1"  # default
+```
+
+Or set them directly:
+
+```python
+ppio_gpus.api_key = "your-api-key"
+ppio_gpus.endpoint_url_base = "https://your-custom-url/v1"
+```

ppio_gpus-0.0.1/README.md

@@ -0,0 +1,71 @@
+# ppio-gpus
+
+Python SDK for PPIO serverless GPU endpoints.
+
+## Installation
+
+```bash
+pip install ppio-gpus
+```
+
+## Quick Start (Client)
+
+```python
+import ppio_gpus
+
+ppio_gpus.api_key = "your-api-key"
+
+endpoint = ppio_gpus.Endpoint("your-endpoint-id")
+job = endpoint.run({"prompt": "hello world"})
+
+print(job.status())
+output = job.output(timeout=60)
+print(output)
+```
+
+## Quick Start (Worker)
+
+```python
+import ppio_gpus
+
+def handler(job):
+    job_input = job["input"]
+    # ... process ...
+    return {"result": "done"}
+
+ppio_gpus.start({"handler": handler})
+```
+
+## Client API
+
+- `Endpoint(endpoint_id)` -- create an endpoint client
+- `Endpoint.run(input)` -- async submit a task, returns a `Job` immediately
+- `Endpoint.health()` -- check endpoint health
+- `Endpoint.purge_queue()` -- cancel all pending tasks
+- `Job.status()` -- get current task status
+- `Job.output(timeout=0)` -- get task output, optionally poll until complete
+- `Job.cancel()` -- cancel a running task
+
+## Worker API
+
+- `ppio_gpus.start(config)` -- start the worker loop (blocks until SIGTERM)
+- `ppio_gpus.progress_update(job, data)` -- send in-progress status update
+- `ppio_gpus.upload_image(job_id, path)` -- upload image to S3, returns presigned URL
+- `ppio_gpus.upload_file(name, path)` -- upload file to S3
+- `ppio_gpus.upload_bytes(name, data)` -- upload bytes to S3
+
+## Configuration
+
+Set credentials via environment variables:
+
+```bash
+export PPIO_API_KEY="your-api-key"
+export PPIO_ENDPOINT_BASE_URL="https://async-public.serverless.ppinfra.com/v1"  # default
+```
+
+Or set them directly:
+
+```python
+ppio_gpus.api_key = "your-api-key"
+ppio_gpus.endpoint_url_base = "https://your-custom-url/v1"
+```

ppio_gpus-0.0.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ppio-gpus"
+version = "0.0.1"
+description = "PPIO GPUs SDK - Python SDK for PPIO serverless GPU endpoints"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "PPIO", email = "support@ppio.com" },
+]
+keywords = ["ppio", "serverless", "gpu", "ai", "inference", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.25.0",
+    "aiohttp>=3.9.0",
+    "aiohttp-retry>=2.8.3",
+    "boto3>=1.28.0",
+    "urllib3>=2.0.0",
+    "filelock>=3.12.0",
+]
+
+[project.urls]
+Homepage = "https://ppio.com/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ppio_gpus"]

ppio_gpus-0.0.1/src/ppio_gpus/__init__.py

@@ -0,0 +1,99 @@
+"""
+PPIO GPUs SDK
+
+Usage (client)::
+
+    import ppio_gpus
+
+    ppio_gpus.api_key = "your-api-key"
+    endpoint = ppio_gpus.Endpoint("your-endpoint-id")
+    job = endpoint.run({"prompt": "hello"})
+    print(job.output(timeout=60))
+
+Usage (worker)::
+
+    import ppio_gpus
+
+    def handler(job):
+        return {"result": job["input"]}
+
+    ppio_gpus.start({"handler": handler})
+"""
+
+import argparse
+import os
+import signal
+import sys
+from typing import Any, Dict
+
+from .client import Endpoint, Job, HTTPClient
+from .modules.logger import PPIOLogger
+from .modules.progress import progress_update
+from .modules.upload import upload_image, upload_images, upload_file, upload_bytes
+from .worker import run_worker
+
+api_key = os.environ.get("PPIO_API_KEY", None)
+endpoint_url_base = os.environ.get(
+    "PPIO_ENDPOINT_BASE_URL", "https://async-public.serverless.ppinfra.com/v1"
+)
+
+__all__ = [
+    # client
+    "Endpoint", "Job", "HTTPClient",
+    "api_key", "endpoint_url_base",
+    # worker
+    "start", "progress_update",
+    "upload_image", "upload_images", "upload_file", "upload_bytes",
+]
+
+log = PPIOLogger()
+
+# ---------------------------------------------------------------------------
+# CLI arguments
+# ---------------------------------------------------------------------------
+_parser = argparse.ArgumentParser(prog="ppio_gpus", description="PPIO Serverless Worker")
+_parser.add_argument(
+    "--log_level",
+    type=str,
+    default=None,
+    help="Log level: ERROR, WARN, INFO, DEBUG (default: DEBUG).",
+)
+
+
+def _set_config_args(config: dict) -> dict:
+    args, unknown = _parser.parse_known_args()
+    sys.argv = [sys.argv[0]] + unknown
+    config["rp_args"] = vars(args)
+
+    if config["rp_args"].get("log_level"):
+        log.set_level(config["rp_args"]["log_level"])
+
+    return config
+
+
+def _signal_handler(sig, frame):
+    del sig, frame
+    log.info("SIGINT received, shutting down.")
+    sys.exit(0)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+def start(config: Dict[str, Any]) -> None:
+    """
+    Start the PPIO serverless worker.
+
+    Args:
+        config: dict with at least ``"handler"`` (Callable).
+                Optional keys:
+                - ``"concurrency_modifier"`` -- callable(int) -> int
+                - ``"refresh_worker"`` -- bool, restart worker after each job
+                - ``"return_aggregate_stream"`` -- bool, accumulate stream chunks
+    """
+    print("--- Starting PPIO Serverless Worker ---")
+
+    signal.signal(signal.SIGINT, _signal_handler)
+    config = _set_config_args(config)
+
+    run_worker(config)

ppio_gpus-0.0.1/src/ppio_gpus/client.py

@@ -0,0 +1,264 @@
+"""
+Async GPU Serverless Client SDK
+
+Shared client module for submitting tasks to the async gateway.
+Provides Endpoint, Job, and HTTPClient classes for async task submission.
+"""
+
+import time
+from typing import Any, Dict, Optional
+
+import requests
+from requests.adapters import HTTPAdapter, Retry
+
+
+API_KEY_NOT_SET_MSG = (
+    "API key has not been set. Please set it via the api_key parameter "
+    "or the appropriate environment variable."
+)
+UNAUTHORIZED_MSG = "Unauthorized — invalid or expired API key."
+FINAL_STATES = {"COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED"}
+
+
+def _is_completed(status: str) -> bool:
+    return status in FINAL_STATES
+
+
+# ---------------------------------------------------------------------------- #
+#                                    Client                                    #
+# ---------------------------------------------------------------------------- #
+class HTTPClient:
+    """A client for making requests to the async-gateway."""
+
+    def __init__(self, api_key: str, endpoint_url_base: str):
+        """
+        Initialize an HTTPClient instance.
+
+        Args:
+            api_key: The API key for authentication.
+            endpoint_url_base: The base URL for the async-gateway v1 API.
+
+        Raises:
+            RuntimeError: If the API key is not provided.
+        """
+        if api_key is None:
+            raise RuntimeError(API_KEY_NOT_SET_MSG)
+
+        self.api_key = api_key
+        self.endpoint_url_base = endpoint_url_base.rstrip("/")
+
+        self.session = requests.Session()
+        retries = Retry(total=5, backoff_factor=1, status_forcelist=[408, 429])
+        self.session.mount("http://", HTTPAdapter(max_retries=retries))
+        self.session.mount("https://", HTTPAdapter(max_retries=retries))
+
+        self.headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+        }
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        data: Optional[dict] = None,
+        timeout: int = 10,
+    ):
+        """
+        Make a request to the specified endpoint using the given HTTP method.
+
+        Args:
+            method: The HTTP method to use ('GET' or 'POST').
+            endpoint: The endpoint path appended to endpoint_url_base.
+            data: The JSON payload to send with the request.
+            timeout: Seconds to wait before giving up.
+
+        Returns:
+            The JSON response from the server.
+
+        Raises:
+            RuntimeError: If the response returns a 401 Unauthorized status.
+            requests.HTTPError: If the response contains an unsuccessful status code.
+        """
+        url = f"{self.endpoint_url_base}/{endpoint}"
+        response = self.session.request(
+            method, url, headers=self.headers, json=data, timeout=timeout
+        )
+
+        if response.status_code == 401:
+            raise RuntimeError(UNAUTHORIZED_MSG)
+
+        response.raise_for_status()
+        return response.json()
+
+    def post(self, endpoint: str, data: Optional[dict] = None, timeout: int = 10):
+        """Post to the endpoint."""
+        return self._request("POST", endpoint, data, timeout)
+
+    def get(self, endpoint: str, timeout: int = 10):
+        """Get from the endpoint."""
+        return self._request("GET", endpoint, timeout=timeout)
+
+
+# ---------------------------------------------------------------------------- #
+#                                      Job                                     #
+# ---------------------------------------------------------------------------- #
+class Job:
+    """Represents a submitted task on the async-gateway."""
+
+    def __init__(self, endpoint_id: str, job_id: str, client: HTTPClient):
+        """
+        Initialize a Job instance.
+
+        Args:
+            endpoint_id: The identifier for the endpoint.
+            job_id: The identifier for the task.
+            client: An HTTPClient instance to make requests with.
+        """
+        self.endpoint_id = endpoint_id
+        self.job_id = job_id
+        self._client = client
+
+        self._status: Optional[str] = None
+        self._output: Optional[Any] = None
+
+    def _fetch_job(self) -> Dict[str, Any]:
+        """Fetch current task state from the gateway."""
+        status_url = f"{self.endpoint_id}/status/{self.job_id}"
+        job_state = self._client.get(endpoint=status_url)
+
+        if _is_completed(job_state["status"]):
+            self._status = job_state["status"]
+            self._output = job_state.get("output", None)
+
+        return job_state
+
+    def status(self) -> str:
+        """
+        Returns the status of the task.
+
+        Terminal states are cached so subsequent calls avoid extra requests.
+        """
+        if self._status is not None:
+            return self._status
+
+        return self._fetch_job()["status"]
+
+    def output(self, timeout: int = 0) -> Any:
+        """
+        Returns the output of the task.
+
+        Args:
+            timeout: If > 0, polls every second until the task reaches a
+                     terminal state or the timeout is exceeded.
+
+        Raises:
+            TimeoutError: If the timeout is exceeded before the task completes.
+        """
+        if timeout > 0:
+            remaining = timeout
+            while not _is_completed(self.status()):
+                time.sleep(1)
+                remaining -= 1
+                if remaining <= 0:
+                    raise TimeoutError("Job timed out.")
+
+        if self._output is not None:
+            return self._output
+
+        return self._fetch_job().get("output", None)
+
+    def cancel(self, timeout: int = 3) -> Any:
+        """
+        Cancel the task.
+
+        Args:
+            timeout: Seconds to wait for the server to respond.
+        """
+        return self._client.post(
+            f"{self.endpoint_id}/cancel/{self.job_id}",
+            data=None,
+            timeout=timeout,
+        )
+
+
+# ---------------------------------------------------------------------------- #
+#                                   Endpoint                                   #
+# ---------------------------------------------------------------------------- #
+class Endpoint:
+    """Manages an endpoint for submitting tasks to the async-gateway."""
+
+    def __init__(
+        self,
+        endpoint_id: str,
+        api_key: Optional[str] = None,
+        endpoint_url_base: Optional[str] = None,
+    ):
+        """
+        Initialize an Endpoint instance.
+
+        If api_key or endpoint_url_base are not provided, the constructor
+        reads module-level globals ``ppio_gpus.api_key`` and
+        ``ppio_gpus.endpoint_url_base``.
+
+        Args:
+            endpoint_id: The identifier for the endpoint.
+            api_key: Optional API key. Falls back to ppio_gpus.api_key.
+            endpoint_url_base: Optional base URL. Falls back to ppio_gpus.endpoint_url_base.
+        """
+        self.endpoint_id = endpoint_id
+
+        resolved_key = api_key
+        resolved_base = endpoint_url_base
+
+        if resolved_key is None or resolved_base is None:
+            import ppio_gpus as _pkg
+            if resolved_key is None:
+                resolved_key = getattr(_pkg, "api_key", None)
+            if resolved_base is None:
+                resolved_base = getattr(_pkg, "endpoint_url_base", None)
+
+        self._client = HTTPClient(api_key=resolved_key, endpoint_url_base=resolved_base)
+
+    def run(self, request_input: Dict[str, Any]) -> Job:
+        """
+        Submit a task to the endpoint.
+
+        Automatically wraps the payload in ``{"input": ...}`` if the dict
+        does not already contain an ``"input"`` key.
+
+        Args:
+            request_input: The input payload for the task.
+
+        Returns:
+            A Job instance for tracking the submitted task.
+        """
+        if "input" not in request_input:
+            request_input = {"input": request_input}
+
+        job_request = self._client.post(
+            f"{self.endpoint_id}/run", request_input
+        )
+        return Job(self.endpoint_id, job_request["id"], self._client)
+
+    def health(self, timeout: int = 3) -> Dict[str, Any]:
+        """
+        Check the health of the endpoint.
+
+        Args:
+            timeout: Seconds to wait for the server to respond.
+        """
+        return self._client.get(
+            f"{self.endpoint_id}/health", timeout=timeout
+        )
+
+    def purge_queue(self, timeout: int = 3) -> Dict[str, Any]:
+        """
+        Purge all pending tasks from the endpoint's queue.
+
+        Args:
+            timeout: Seconds to wait for the server to respond.
+        """
+        return self._client.post(
+            f"{self.endpoint_id}/purge-queue", data=None, timeout=timeout
+        )

ppio_gpus-0.0.1/src/ppio_gpus/http_client.py

@@ -0,0 +1,40 @@
+"""
+HTTP Client abstractions
+"""
+
+import os
+
+import requests
+from aiohttp import ClientSession, ClientTimeout, TCPConnector, ClientResponseError
+
+
+class TooManyRequests(ClientResponseError):
+    pass
+
+
+def _get_auth_header():
+    # PPIO_AI_API_KEY already contains "Bearer <jwt>" when JWT auth is configured.
+    auth_value = os.environ.get("PPIO_AI_API_KEY", "")
+    return {
+        "Content-Type": "application/json",
+        "Authorization": auth_value,
+        "Accept-Encoding": "gzip, deflate",
+    }
+
+
+def AsyncClientSession(*args, **kwargs):  # pylint: disable=invalid-name
+    """
+    Factory for aiohttp.ClientSession pre-configured for the PPIO async gateway.
+    """
+    return ClientSession(
+        connector=TCPConnector(limit=0),
+        headers=_get_auth_header(),
+        timeout=ClientTimeout(600, ceil_threshold=400),
+        *args,
+        **kwargs,
+    )
+
+
+class SyncClientSession(requests.Session):
+    """Thin wrapper around requests.Session."""
+    pass

ppio_gpus-0.0.1/src/ppio_gpus/modules/__init__.py

@@ -0,0 +1 @@
+from ppio_gpus.modules import handler, job, logger, ping, progress, scale, upload, worker_state

ppio_gpus-0.0.1/src/ppio_gpus/modules/handler.py

@@ -0,0 +1,9 @@
+"""Handler introspection utilities."""
+
+import inspect
+from typing import Callable
+
+
+def is_generator(handler: Callable) -> bool:
+    """Return True if handler is a (async) generator function."""
+    return inspect.isgeneratorfunction(handler) or inspect.isasyncgenfunction(handler)