hypercli-sdk 0.4.2__py3-none-any.whl

c3/http.py

@@ -0,0 +1,217 @@
+"""HTTP client utilities"""
+import time
+import httpx
+from typing import Any, Optional, Iterator, Callable
+from dataclasses import dataclass
+
+
+def request_with_retry(
+    method: str,
+    url: str,
+    headers: dict = None,
+    retries: int = 3,
+    backoff: float = 1.0,
+    timeout: float = 30.0,
+    **kwargs,
+) -> httpx.Response:
+    """Make an HTTP request with retry logic for transient errors.
+
+    Args:
+        method: HTTP method (get, post, etc.)
+        url: Full URL to request
+        headers: Request headers
+        retries: Number of retry attempts
+        backoff: Backoff multiplier between retries
+        timeout: Request timeout in seconds
+        **kwargs: Additional args passed to httpx (json, params, etc.)
+
+    Returns:
+        httpx.Response
+
+    Raises:
+        Last exception if all retries fail
+    """
+    last_error = None
+    for attempt in range(retries):
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                resp = getattr(client, method)(url, headers=headers, **kwargs)
+                return resp
+        except (httpx.ProxyError, httpx.ConnectError, httpx.ReadTimeout) as e:
+            last_error = e
+            if attempt < retries - 1:
+                time.sleep(backoff * (attempt + 1))
+                continue
+            raise
+    raise last_error
+
+
+@dataclass
+class APIError(Exception):
+    """API error with status code and detail"""
+    status_code: int
+    detail: str
+
+    def __str__(self):
+        return f"API Error {self.status_code}: {self.detail}"
+
+
+def _handle_response(response: httpx.Response) -> Any:
+    """Handle API response, raise on error"""
+    if response.status_code >= 400:
+        try:
+            detail = response.json().get("detail", response.text)
+        except Exception:
+            detail = response.text
+        raise APIError(response.status_code, detail)
+    if response.status_code == 204:
+        return None
+    return response.json()
+
+
+class HTTPClient:
+    """Sync HTTP client"""
+
+    def __init__(self, base_url: str, api_key: str, timeout: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    @property
+    def headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def get(self, path: str, params: dict = None) -> Any:
+        resp = request_with_retry(
+            "get", f"{self.base_url}{path}",
+            headers=self.headers, timeout=self.timeout, params=params
+        )
+        return _handle_response(resp)
+
+    def post(self, path: str, json: dict = None) -> Any:
+        resp = request_with_retry(
+            "post", f"{self.base_url}{path}",
+            headers=self.headers, timeout=self.timeout, json=json
+        )
+        return _handle_response(resp)
+
+    def patch(self, path: str, json: dict = None) -> Any:
+        resp = request_with_retry(
+            "patch", f"{self.base_url}{path}",
+            headers=self.headers, timeout=self.timeout, json=json
+        )
+        return _handle_response(resp)
+
+    def delete(self, path: str) -> Any:
+        resp = request_with_retry(
+            "delete", f"{self.base_url}{path}",
+            headers=self.headers, timeout=self.timeout
+        )
+        return _handle_response(resp)
+
+    def stream_post(self, path: str, json: dict) -> Iterator[str]:
+        """Streaming POST for SSE responses"""
+        with httpx.Client(timeout=None) as client:
+            with client.stream(
+                "POST",
+                f"{self.base_url}{path}",
+                headers=self.headers,
+                json=json,
+            ) as response:
+                if response.status_code >= 400:
+                    raise APIError(response.status_code, response.read().decode())
+                for line in response.iter_lines():
+                    yield line
+
+    def post_multipart(self, path: str, files: dict) -> Any:
+        """POST with multipart form data for file uploads.
+
+        Args:
+            path: API path
+            files: Dict of {field_name: file_tuple} where file_tuple is
+                   (filename, file_bytes, content_type) or just file_bytes
+        """
+        # Build headers without Content-Type (httpx sets it for multipart)
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.post(
+                f"{self.base_url}{path}",
+                headers=headers,
+                files=files,
+            )
+            return _handle_response(response)
+
+
+class AsyncHTTPClient:
+    """Async HTTP client for use in async contexts (e.g., Telegram bot, web servers)"""
+
+    def __init__(self, base_url: str, api_key: str, timeout: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    @property
+    def headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    async def get(self, path: str, params: dict = None) -> Any:
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(
+                f"{self.base_url}{path}",
+                headers=self.headers,
+                params=params,
+            )
+            return _handle_response(response)
+
+    async def post(self, path: str, json: dict = None) -> Any:
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.post(
+                f"{self.base_url}{path}",
+                headers=self.headers,
+                json=json,
+            )
+            return _handle_response(response)
+
+    async def patch(self, path: str, json: dict = None) -> Any:
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.patch(
+                f"{self.base_url}{path}",
+                headers=self.headers,
+                json=json,
+            )
+            return _handle_response(response)
+
+    async def delete(self, path: str) -> Any:
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.delete(
+                f"{self.base_url}{path}",
+                headers=self.headers,
+            )
+            return _handle_response(response)
+
+    async def post_multipart(self, path: str, files: dict, params: dict = None) -> Any:
+        """POST with multipart form data for file uploads.
+
+        Args:
+            path: API path
+            files: Dict of {field_name: file_tuple} where file_tuple is
+                   (filename, file_bytes, content_type) or just file_bytes
+            params: Optional query parameters
+        """
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.post(
+                f"{self.base_url}{path}",
+                headers=headers,
+                files=files,
+                params=params,
+            )
+            return _handle_response(response)

c3/instances.py

@@ -0,0 +1,211 @@
+"""Instances API - GPU types, regions, and pricing"""
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .http import HTTPClient
+
+
+@dataclass
+class GPUConfig:
+    """Configuration for a specific GPU count"""
+    gpu_count: int
+    cpu_cores: float
+    memory_gb: float
+    storage_gb: float
+    regions: list[str]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "GPUConfig":
+        return cls(
+            gpu_count=data.get("gpu_count", 1),
+            cpu_cores=data.get("cpu_cores", 0),
+            memory_gb=data.get("memory_gb", 0),
+            storage_gb=data.get("storage_gb", 0),
+            regions=data.get("regions", []),
+        )
+
+
+@dataclass
+class GPUType:
+    """GPU type with its configurations"""
+    id: str
+    name: str
+    description: str
+    configs: list[GPUConfig]
+
+    @classmethod
+    def from_dict(cls, id: str, data: dict) -> "GPUType":
+        return cls(
+            id=id,
+            name=data.get("name", id),
+            description=data.get("description", ""),
+            configs=[GPUConfig.from_dict(c) for c in data.get("configs", [])],
+        )
+
+    def available_regions(self, gpu_count: int = 1) -> list[str]:
+        """Get regions where this GPU is available for given count"""
+        for config in self.configs:
+            if config.gpu_count == gpu_count:
+                return config.regions
+        return []
+
+    def available_counts(self) -> list[int]:
+        """Get available GPU counts for this type"""
+        return [c.gpu_count for c in self.configs if c.regions]
+
+
+@dataclass
+class Region:
+    """A datacenter region"""
+    id: str
+    description: str
+    country: str
+
+    @classmethod
+    def from_dict(cls, id: str, data: dict) -> "Region":
+        return cls(
+            id=id,
+            description=data.get("description", id),
+            country=data.get("country", ""),
+        )
+
+
+@dataclass
+class PricingTier:
+    """Pricing for a specific region"""
+    region: str
+    on_demand: float | None = None
+    interruptible: float | None = None
+
+    @classmethod
+    def from_dict(cls, region: str, data: dict) -> "PricingTier":
+        return cls(
+            region=region,
+            on_demand=data.get("on-demand"),
+            interruptible=data.get("interruptable"),  # Note: API has typo
+        )
+
+
+@dataclass
+class GPUPricing:
+    """Pricing for a GPU configuration"""
+    gpu_type: str
+    gpu_count: int
+    tiers: list[PricingTier]
+
+    @classmethod
+    def from_key(cls, key: str, data: dict) -> "GPUPricing":
+        # Parse key like "h100_x8" -> gpu_type="h100", gpu_count=8
+        parts = key.rsplit("_x", 1)
+        gpu_type = parts[0]
+        gpu_count = int(parts[1]) if len(parts) > 1 else 1
+
+        tiers = [PricingTier.from_dict(region, prices) for region, prices in data.items()]
+        return cls(gpu_type=gpu_type, gpu_count=gpu_count, tiers=tiers)
+
+    def get_price(self, region: str, interruptible: bool = True) -> float | None:
+        """Get price for a specific region and tier"""
+        for tier in self.tiers:
+            if tier.region == region:
+                return tier.interruptible if interruptible else tier.on_demand
+        return None
+
+
+class Instances:
+    """Instances API - GPU types, regions, and pricing"""
+
+    def __init__(self, http: "HTTPClient"):
+        self._http = http
+        self._types_cache: dict[str, GPUType] | None = None
+        self._regions_cache: dict[str, Region] | None = None
+        self._pricing_cache: dict[str, GPUPricing] | None = None
+
+    def types(self, refresh: bool = False) -> dict[str, GPUType]:
+        """Get available GPU types"""
+        if self._types_cache is None or refresh:
+            data = self._http.get("/instances/types")
+            self._types_cache = {
+                id: GPUType.from_dict(id, info) for id, info in data.items()
+            }
+        return self._types_cache
+
+    def regions(self, refresh: bool = False) -> dict[str, Region]:
+        """Get available regions"""
+        if self._regions_cache is None or refresh:
+            data = self._http.get("/instances/regions")
+            self._regions_cache = {
+                id: Region.from_dict(id, info) for id, info in data.items()
+            }
+        return self._regions_cache
+
+    def pricing(self, refresh: bool = False) -> dict[str, GPUPricing]:
+        """Get pricing information"""
+        if self._pricing_cache is None or refresh:
+            data = self._http.get("/instances/pricing")
+            self._pricing_cache = {
+                key: GPUPricing.from_key(key, prices) for key, prices in data.items()
+            }
+        return self._pricing_cache
+
+    def get_type(self, gpu_type: str) -> GPUType | None:
+        """Get a specific GPU type by ID"""
+        return self.types().get(gpu_type)
+
+    def get_region(self, region_id: str) -> Region | None:
+        """Get a specific region by ID"""
+        return self.regions().get(region_id)
+
+    def get_price(
+        self, gpu_type: str, gpu_count: int = 1, region: str = None, interruptible: bool = True
+    ) -> float | None:
+        """Get price for a specific GPU configuration"""
+        key = f"{gpu_type}_x{gpu_count}"
+        pricing = self.pricing().get(key)
+        if pricing and region:
+            return pricing.get_price(region, interruptible)
+        return None
+
+    def list_available(self, gpu_type: str = None, region: str = None) -> list[dict]:
+        """List available GPU configurations, optionally filtered"""
+        types = self.types()
+        regions = self.regions()
+        pricing = self.pricing()
+
+        results = []
+        for type_id, gpu in types.items():
+            if gpu_type and type_id != gpu_type:
+                continue
+
+            for config in gpu.configs:
+                if not config.regions:
+                    continue
+                if region and region not in config.regions:
+                    continue
+
+                key = f"{type_id}_x{config.gpu_count}"
+                gpu_pricing = pricing.get(key)
+
+                for r in config.regions:
+                    if region and r != region:
+                        continue
+
+                    region_info = regions.get(r)
+                    price_info = gpu_pricing.get_price(r, True) if gpu_pricing else None
+                    on_demand_price = gpu_pricing.get_price(r, False) if gpu_pricing else None
+
+                    results.append({
+                        "gpu_type": type_id,
+                        "gpu_name": gpu.name,
+                        "gpu_count": config.gpu_count,
+                        "cpu_cores": config.cpu_cores,
+                        "memory_gb": config.memory_gb,
+                        "storage_gb": config.storage_gb,
+                        "region": r,
+                        "region_name": region_info.description if region_info else r,
+                        "country": region_info.country if region_info else "",
+                        "price_spot": price_info,
+                        "price_on_demand": on_demand_price,
+                    })
+
+        return results

c3/job/__init__.py

@@ -0,0 +1,24 @@
+"""Job helpers for different GPU workload types"""
+from .base import BaseJob
+from .comfyui import (
+    ComfyUIJob,
+    apply_params,
+    apply_graph_modes,
+    find_node,
+    find_nodes,
+    load_template,
+    graph_to_api,
+    DEFAULT_OBJECT_INFO,
+)
+
+__all__ = [
+    "BaseJob",
+    "ComfyUIJob",
+    "apply_params",
+    "apply_graph_modes",
+    "find_node",
+    "find_nodes",
+    "load_template",
+    "graph_to_api",
+    "DEFAULT_OBJECT_INFO",
+]

c3/job/base.py

@@ -0,0 +1,249 @@
+"""Base job class for GPU workloads"""
+import time
+import httpx
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import C3
+    from ..jobs import Job
+
+
+class BaseJob:
+    """Base class for managed GPU jobs with lifecycle helpers"""
+
+    DEFAULT_IMAGE: str = ""
+    DEFAULT_GPU_TYPE: str = "l40s"
+    HEALTH_ENDPOINT: str = "/"
+    HEALTH_TIMEOUT: float = 5.0
+
+    def __init__(self, c3: "C3", job: "Job"):
+        self.c3 = c3
+        self.job = job
+        self._base_url: str | None = None
+
+    @property
+    def job_id(self) -> str:
+        return self.job.job_id
+
+    @property
+    def hostname(self) -> str | None:
+        return self.job.hostname
+
+    @property
+    def base_url(self) -> str:
+        """Base URL - only valid after job is running"""
+        if not self._base_url and self.hostname:
+            self._base_url = f"http://{self.hostname}"
+        return self._base_url or ""
+
+    @property
+    def auth_headers(self) -> dict:
+        """Headers for authenticated requests. Override in subclasses for custom auth."""
+        return {"Authorization": f"Bearer {self.c3._api_key}"}
+
+    @classmethod
+    def get_running(cls, c3: "C3", image_filter: str = None) -> "BaseJob | None":
+        """Find an existing running job, optionally filtering by image"""
+        jobs = c3.jobs.list(state="running")
+        for job in jobs:
+            if image_filter and image_filter not in job.docker_image:
+                continue
+            return cls(c3, job)
+        return None
+
+    @classmethod
+    def get_by_instance(cls, c3: "C3", instance: str, state: str = "running") -> "BaseJob":
+        """Get a job by ID, hostname, or IP address.
+
+        Args:
+            c3: C3 client
+            instance: Job ID (UUID), hostname (partial match), or IP address
+            state: State filter for hostname/IP search (default: running)
+
+        Returns:
+            Job wrapper instance
+
+        Raises:
+            ValueError: If no matching job found
+        """
+        from ..jobs import find_job
+
+        job = find_job(c3.jobs, instance, state=state)
+        if not job:
+            raise ValueError(f"No job found matching: {instance}")
+        return cls(c3, job)
+
+    @classmethod
+    def create(
+        cls,
+        c3: "C3",
+        image: str = None,
+        gpu_type: str = None,
+        gpu_count: int = 1,
+        runtime: int = 3600,
+        **kwargs,
+    ) -> "BaseJob":
+        """Create a new job"""
+        job = c3.jobs.create(
+            image=image or cls.DEFAULT_IMAGE,
+            gpu_type=gpu_type or cls.DEFAULT_GPU_TYPE,
+            gpu_count=gpu_count,
+            runtime=runtime,
+            **kwargs,
+        )
+        return cls(c3, job)
+
+    @classmethod
+    def get_or_create(
+        cls,
+        c3: "C3",
+        image: str = None,
+        gpu_type: str = None,
+        gpu_count: int = 1,
+        runtime: int = 3600,
+        reuse: bool = True,
+        **kwargs,
+    ) -> "BaseJob":
+        """Get existing running job or create new one"""
+        if reuse:
+            existing = cls.get_running(c3, image_filter=image or cls.DEFAULT_IMAGE)
+            if existing:
+                return existing
+
+        return cls.create(
+            c3,
+            image=image,
+            gpu_type=gpu_type,
+            gpu_count=gpu_count,
+            runtime=runtime,
+            **kwargs,
+        )
+
+    def refresh(self) -> "BaseJob":
+        """Refresh job state from API"""
+        self.job = self.c3.jobs.get(self.job_id)
+        self._base_url = None
+        return self
+
+    def wait_for_running(self, timeout: float = 300, poll_interval: float = 5) -> bool:
+        """Wait for job to reach running state via API polling.
+
+        IMPORTANT: Do not attempt to connect to hostname until this returns True.
+        Connecting before the job is running will cache NXDOMAIN in DNS for ~30 mins.
+        """
+        start = time.time()
+        while time.time() - start < timeout:
+            self.refresh()
+            if self.job.state == "running" and self.hostname:
+                return True
+            if self.job.state in ("failed", "cancelled", "completed", "terminated"):
+                return False
+            time.sleep(poll_interval)
+        return False
+
+    def wait_for_hostname(self, timeout: float = 300, poll_interval: float = 5) -> bool:
+        """Alias for wait_for_running - waits for job to be running with hostname"""
+        return self.wait_for_running(timeout=timeout, poll_interval=poll_interval)
+
+    def check_health(self) -> bool:
+        """Check if the service is responding.
+
+        Only call this after job is confirmed running via wait_for_running().
+        """
+        if not self.base_url or self.job.state != "running":
+            return False
+        try:
+            from c3.http import request_with_retry
+            resp = request_with_retry(
+                "get",
+                f"{self.base_url}{self.HEALTH_ENDPOINT}",
+                headers=self.auth_headers,
+                timeout=self.HEALTH_TIMEOUT,
+                retries=3,
+            )
+            return resp.status_code == 200
+        except Exception:
+            return False
+
+    def wait_existing(self, timeout: float = 15) -> bool:
+        """Wait for an EXISTING running job to respond to health checks.
+
+        Use when reconnecting to a job that was already running (e.g., service restart,
+        reusing an idle instance). No DNS delay needed because the hostname was already
+        resolved previously - DNS is cached and propagated.
+
+        Args:
+            timeout: Max seconds to wait for health check (default 15s). Short because
+                     if an existing healthy job doesn't respond quickly, it's likely dead.
+
+        Returns:
+            True if job is running and healthy, False otherwise
+        """
+        self.refresh()
+        if self.job.state != "running" or not self.hostname:
+            return False
+
+        start = time.time()
+        while time.time() - start < timeout:
+            if self.check_health():
+                return True
+            time.sleep(2)
+        return False
+
+    def wait_ready(
+        self, timeout: float = 300, poll_interval: float = 5, dns_delay: float = 15.0
+    ) -> bool:
+        """Wait for a NEW job to be ready (running state + health check passing).
+
+        For newly launched jobs only. Use wait_existing() for jobs already running.
+
+        Flow:
+        1. Poll API until job state = "running" (no DNS lookups yet)
+        2. Wait dns_delay seconds for DNS to propagate
+        3. Poll health endpoint until service responds
+
+        Why dns_delay? New jobs get fresh hostnames. If we hit DNS before it propagates,
+        we get NXDOMAIN which gets cached by the resolver for ~30 minutes, breaking all
+        subsequent requests. The 15s delay lets DNS propagate first. ComfyUI takes >30s
+        to boot anyway, so this doesn't add latency.
+
+        Args:
+            timeout: Total max seconds to wait (default 300s). Includes API polling +
+                     DNS delay + health checks.
+            poll_interval: Seconds between API state checks (default 5s).
+            dns_delay: Seconds to wait after API says "running" before first DNS lookup
+                       (default 15s). Prevents NXDOMAIN caching on new hostnames.
+        """
+        start = time.time()
+
+        # Wait for running state via API (no DNS calls yet)
+        self.refresh()
+        if self.job.state in ("failed", "cancelled", "completed", "terminated"):
+            return False
+
+        if self.job.state != "running" or not self.hostname:
+            if not self.wait_for_running(timeout=timeout, poll_interval=poll_interval):
+                return False
+
+        # DNS propagation delay - wait before first hostname lookup to avoid NXDOMAIN caching
+        if dns_delay > 0:
+            time.sleep(dns_delay)
+
+        # Job is running, check health with shorter interval
+        elapsed = time.time() - start
+        remaining = timeout - elapsed
+        while remaining > 0:
+            if self.check_health():
+                return True
+            time.sleep(2)  # Shorter interval for health checks
+            remaining = timeout - (time.time() - start)
+        return False
+
+    def shutdown(self) -> dict:
+        """Cancel the job"""
+        return self.c3.jobs.cancel(self.job_id)
+
+    def extend(self, runtime: int) -> "BaseJob":
+        """Extend job runtime"""
+        self.job = self.c3.jobs.extend(self.job_id, runtime=runtime)
+        return self