hypercli-sdk 0.4.2__py3-none-any.whl

c3/__init__.py

@@ -0,0 +1,57 @@
+"""C3 SDK - Python client for HyperCLI API"""
+from .client import C3
+from .config import configure, GHCR_IMAGES, COMFYUI_IMAGE
+from .http import APIError, AsyncHTTPClient
+from .instances import GPUType, GPUConfig, Region, GPUPricing, PricingTier
+from .jobs import Job, JobMetrics, GPUMetrics, find_job, find_by_id, find_by_hostname, find_by_ip
+from .renders import Render, RenderStatus
+from .files import File, AsyncFiles
+from .job import BaseJob, ComfyUIJob, apply_params, apply_graph_modes, find_node, find_nodes, load_template, graph_to_api, DEFAULT_OBJECT_INFO
+from .logs import LogStream, stream_logs, fetch_logs
+
+__version__ = "0.2.1"
+__all__ = [
+    "C3",
+    "configure",
+    "APIError",
+    # Images
+    "GHCR_IMAGES",
+    "COMFYUI_IMAGE",
+    # Instance types
+    "GPUType",
+    "GPUConfig",
+    "Region",
+    "GPUPricing",
+    "PricingTier",
+    # Jobs API
+    "Job",
+    "JobMetrics",
+    "GPUMetrics",
+    # Renders API
+    "Render",
+    "RenderStatus",
+    # Files API
+    "File",
+    "AsyncFiles",
+    "AsyncHTTPClient",
+    # Job lookup utils
+    "find_job",
+    "find_by_id",
+    "find_by_hostname",
+    "find_by_ip",
+    # Job helpers
+    "BaseJob",
+    "ComfyUIJob",
+    # Workflow utils
+    "apply_params",
+    "apply_graph_modes",
+    "find_node",
+    "find_nodes",
+    "load_template",
+    "graph_to_api",
+    "DEFAULT_OBJECT_INFO",
+    # Log streaming
+    "LogStream",
+    "stream_logs",
+    "fetch_logs",
+]

c3/billing.py

@@ -0,0 +1,72 @@
+"""Billing API"""
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .http import HTTPClient
+
+
+@dataclass
+class Balance:
+    total: str
+    rewards: str
+    paid: str
+    available: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Balance":
+        return cls(
+            total=data.get("total_balance", "0"),
+            rewards=data.get("rewards_balance", "0"),
+            paid=data.get("balance", "0"),
+            available=data.get("available_balance", "0"),
+        )
+
+
+@dataclass
+class Transaction:
+    id: str
+    user_id: str
+    amount: int
+    amount_usd: float
+    transaction_type: str
+    status: str
+    rewards: bool
+    job_id: str | None
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Transaction":
+        return cls(
+            id=data.get("id", ""),
+            user_id=data.get("user_id", ""),
+            amount=data.get("amount", 0),
+            amount_usd=data.get("amount_usd", 0),
+            transaction_type=data.get("transaction_type", ""),
+            status=data.get("status", ""),
+            rewards=data.get("rewards", False),
+            job_id=data.get("job_id"),
+            created_at=data.get("created_at", ""),
+        )
+
+
+class Billing:
+    """Billing API wrapper"""
+
+    def __init__(self, http: "HTTPClient"):
+        self._http = http
+
+    def balance(self) -> Balance:
+        """Get account balance"""
+        data = self._http.get("/api/balance")
+        return Balance.from_dict(data)
+
+    def transactions(self, limit: int = 50, page: int = 1) -> list[Transaction]:
+        """List transactions"""
+        data = self._http.get("/api/tx", params={"page": page, "page_size": limit})
+        return [Transaction.from_dict(tx) for tx in data.get("transactions", [])]
+
+    def get_transaction(self, transaction_id: str) -> Transaction:
+        """Get a specific transaction"""
+        data = self._http.get(f"/api/tx/{transaction_id}")
+        return Transaction.from_dict(data)

c3/client.py

@@ -0,0 +1,60 @@
+"""Main C3 client"""
+from .config import get_api_key, get_api_url
+from .http import HTTPClient
+from .billing import Billing
+from .jobs import Jobs
+from .user import UserAPI
+from .instances import Instances
+from .renders import Renders
+from .files import Files
+
+
+class C3:
+    """
+    C3 API Client
+
+    Usage:
+        from c3 import C3
+
+        c3 = C3()  # Uses C3_API_KEY from env or ~/.c3/config
+        # or
+        c3 = C3(api_key="your_key")
+
+        # Billing
+        balance = c3.billing.balance()
+        print(f"Balance: ${balance.total}")
+
+        # Jobs
+        job = c3.jobs.create(
+            image="nvidia/cuda:12.0",
+            gpu_type="l40s",
+            command="python train.py"
+        )
+        print(f"Job: {job.job_id}")
+
+        # User
+        user = c3.user.get()
+    """
+
+    def __init__(self, api_key: str = None, api_url: str = None):
+        self._api_key = api_key or get_api_key()
+        if not self._api_key:
+            raise ValueError(
+                "API key required. Set C3_API_KEY env var, "
+                "create ~/.c3/config, or pass api_key parameter."
+            )
+
+        self._api_url = api_url or get_api_url()
+        self._http = HTTPClient(self._api_url, self._api_key)
+
+        # API namespaces
+        self.billing = Billing(self._http)
+        self.jobs = Jobs(self._http)
+        self.user = UserAPI(self._http)
+        self.instances = Instances(self._http)
+        self.renders = Renders(self._http)
+        self.files = Files(self._http)
+
+    @property
+    def api_url(self) -> str:
+        return self._api_url

c3/config.py

@@ -0,0 +1,70 @@
+"""Configuration handling"""
+import os
+from pathlib import Path
+from typing import Optional
+
+CONFIG_DIR = Path.home() / ".c3"
+CONFIG_FILE = CONFIG_DIR / "config"
+
+DEFAULT_API_URL = "https://api.hypercli.com"
+DEFAULT_WS_URL = "wss://api.hypercli.com"
+WS_LOGS_PATH = "/orchestra/ws/logs"  # WebSocket path for job logs: {WS_URL}{WS_LOGS_PATH}/{job_key}
+
+# GHCR images
+GHCR_IMAGES = "ghcr.io/hypercliai/images"
+COMFYUI_IMAGE = f"{GHCR_IMAGES}/comfyui"
+
+
+def _load_config_file() -> dict:
+    """Load config from ~/.c3/config"""
+    config = {}
+    if CONFIG_FILE.exists():
+        for line in CONFIG_FILE.read_text().splitlines():
+            line = line.strip()
+            if line and not line.startswith("#") and "=" in line:
+                key, value = line.split("=", 1)
+                config[key.strip()] = value.strip()
+    return config
+
+
+def get_config_value(key: str, default: str = None) -> Optional[str]:
+    """Get config value: env var > config file > default"""
+    env_val = os.getenv(key)
+    if env_val:
+        return env_val
+    config = _load_config_file()
+    return config.get(key, default)
+
+
+def get_api_key() -> Optional[str]:
+    """Get API key from env or config file"""
+    return get_config_value("C3_API_KEY")
+
+
+def get_api_url() -> str:
+    """Get API URL"""
+    return get_config_value("C3_API_URL", DEFAULT_API_URL)
+
+
+def get_ws_url() -> str:
+    """Get WebSocket URL"""
+    ws = get_config_value("C3_WS_URL")
+    if ws:
+        return ws
+    # Derive from API URL
+    api = get_api_url()
+    return api.replace("https://", "wss://").replace("http://", "ws://")
+
+
+def configure(api_key: str, api_url: str = None):
+    """Save configuration to ~/.c3/config"""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    config = _load_config_file()
+    config["C3_API_KEY"] = api_key
+    if api_url:
+        config["C3_API_URL"] = api_url
+
+    lines = [f"{k}={v}" for k, v in config.items()]
+    CONFIG_FILE.write_text("\n".join(lines) + "\n")
+    CONFIG_FILE.chmod(0o600)

c3/files.py

@@ -0,0 +1,386 @@
+"""Files API"""
+import os
+import time
+import asyncio
+import mimetypes
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .http import HTTPClient, AsyncHTTPClient
+
+
+@dataclass
+class File:
+    """Uploaded file metadata.
+
+    The `url` field is an internal reference (s3://...) that can only be used
+    within the HyperCLI platform (e.g., as image_url in render calls).
+    It cannot be used for direct downloads or sharing.
+    """
+    id: str
+    user_id: str
+    filename: str
+    content_type: str
+    file_size: int
+    url: str  # Internal S3 reference - only valid for use in C3 renders
+    state: str | None = None  # processing, done, failed (for async uploads)
+    error: str | None = None  # Error message if state=failed
+    created_at: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "File":
+        return cls(
+            id=data.get("id", ""),
+            user_id=data.get("user_id", ""),
+            filename=data.get("filename", ""),
+            content_type=data.get("content_type", ""),
+            file_size=data.get("file_size", 0),
+            url=data.get("url", ""),
+            state=data.get("state"),
+            error=data.get("error"),
+            created_at=data.get("created_at"),
+        )
+
+    @property
+    def is_ready(self) -> bool:
+        """Check if file upload is complete and ready to use."""
+        return self.state == "done"
+
+    @property
+    def is_failed(self) -> bool:
+        """Check if file upload failed."""
+        return self.state == "failed"
+
+    @property
+    def is_processing(self) -> bool:
+        """Check if file upload is still processing."""
+        return self.state == "processing"
+
+
+class Files:
+    """Files API wrapper for uploading assets"""
+
+    def __init__(self, http: "HTTPClient"):
+        self._http = http
+
+    def upload(self, file_path: str) -> File:
+        """Upload a file for use in renders.
+
+        Args:
+            file_path: Path to local file (image, audio, or video)
+
+        Returns:
+            File object with id and internal url for use in render calls.
+            The url is an S3 reference that only works within C3.
+
+        Example:
+            file = c3.files.upload("./my_image.png")
+            render = c3.renders.image_to_video("dancing", file.url)
+        """
+        # Read file
+        with open(file_path, "rb") as f:
+            content = f.read()
+
+        filename = os.path.basename(file_path)
+
+        # Guess content type
+        content_type, _ = mimetypes.guess_type(file_path)
+        if not content_type:
+            content_type = "application/octet-stream"
+
+        # Upload via multipart
+        files = {"file": (filename, content, content_type)}
+        data = self._http.post_multipart("/api/files/multi", files=files)
+        return File.from_dict(data)
+
+    def upload_bytes(self, content: bytes, filename: str, content_type: str) -> File:
+        """Upload file bytes directly.
+
+        Args:
+            content: File bytes
+            filename: Filename to use
+            content_type: MIME type (e.g., "image/png", "audio/mp3")
+
+        Returns:
+            File object with id and url for use in render calls
+
+        Example:
+            file = c3.files.upload_bytes(image_bytes, "image.png", "image/png")
+        """
+        files = {"file": (filename, content, content_type)}
+        data = self._http.post_multipart("/api/files/multi", files=files)
+        return File.from_dict(data)
+
+    def upload_url(self, url: str, path: str | None = None) -> File:
+        """Upload a file from a URL (async backend processing).
+
+        The backend downloads the file from the URL and uploads it to storage.
+        Returns immediately with state=processing. Use wait_ready() or poll get().
+
+        Args:
+            url: The URL to download the file from
+            path: Optional path prefix for organizing files
+
+        Returns:
+            File object with id and state=processing.
+
+        Example:
+            file = c3.files.upload_url("https://example.com/image.png")
+            file = c3.files.wait_ready(file.id)  # Wait for completion
+        """
+        payload = {"url": url}
+        if path:
+            payload["path"] = path
+        data = self._http.post("/api/files/url", json=payload)
+        return File.from_dict(data)
+
+    def upload_b64(
+        self,
+        data: str,
+        filename: str,
+        content_type: str | None = None,
+        path: str | None = None,
+    ) -> File:
+        """Upload a file from base64-encoded data (async backend processing).
+
+        The backend decodes the base64 data and uploads it to storage.
+        Returns immediately with state=processing. Use wait_ready() or poll get().
+
+        Args:
+            data: Base64-encoded file content
+            filename: Filename to use (e.g., "image.jpg")
+            content_type: MIME type (auto-detected from filename if not provided)
+            path: Optional path prefix for organizing files
+
+        Returns:
+            File object with id and state=processing.
+
+        Example:
+            import base64
+            b64_data = base64.b64encode(image_bytes).decode()
+            file = c3.files.upload_b64(b64_data, "image.png", "image/png")
+            file = c3.files.wait_ready(file.id)
+        """
+        payload = {"data": data, "filename": filename}
+        if content_type:
+            payload["content_type"] = content_type
+        if path:
+            payload["path"] = path
+        result = self._http.post("/api/files/b64", json=payload)
+        return File.from_dict(result)
+
+    def get(self, file_id: str) -> File:
+        """Get file metadata and URL.
+
+        Args:
+            file_id: The file ID
+
+        Returns:
+            File object with url for use in render calls
+        """
+        data = self._http.get(f"/api/files/{file_id}")
+        return File.from_dict(data)
+
+    def delete(self, file_id: str) -> dict:
+        """Delete an uploaded file.
+
+        Args:
+            file_id: The file ID to delete
+
+        Returns:
+            {"status": "deleted", "id": "..."}
+        """
+        return self._http.delete(f"/api/files/{file_id}")
+
+    def wait_ready(
+        self,
+        file_id: str,
+        timeout: float = 60.0,
+        poll_interval: float = 1.0,
+    ) -> File:
+        """Wait for an async upload to complete.
+
+        Polls the file status until it's done or failed.
+
+        Args:
+            file_id: The file ID to wait for
+            timeout: Maximum time to wait in seconds
+            poll_interval: Time between polls in seconds
+
+        Returns:
+            File object with final state (done or failed)
+
+        Raises:
+            TimeoutError: If file doesn't complete within timeout
+            ValueError: If file upload failed
+
+        Example:
+            file = c3.files.upload_url("https://example.com/image.png")
+            file = c3.files.wait_ready(file.id, timeout=30)
+            print(f"Ready: {file.url}")
+        """
+        start = time.time()
+        while time.time() - start < timeout:
+            file = self.get(file_id)
+            if file.is_ready:
+                return file
+            if file.is_failed:
+                raise ValueError(f"File upload failed: {file.error}")
+            time.sleep(poll_interval)
+        raise TimeoutError(f"File {file_id} did not complete within {timeout}s")
+
+
+class AsyncFiles:
+    """Async Files API wrapper for uploading assets in async contexts.
+
+    Use this in async applications like Telegram bots, web servers, etc.
+    """
+
+    def __init__(self, http: "AsyncHTTPClient"):
+        self._http = http
+
+    async def upload_bytes(
+        self,
+        content: bytes,
+        filename: str,
+        content_type: str,
+        path: str | None = None,
+    ) -> File:
+        """Upload file bytes directly.
+
+        Args:
+            content: File bytes
+            filename: Filename to use
+            content_type: MIME type (e.g., "image/png", "audio/mp3")
+            path: Optional path prefix for organizing files (e.g., "telegram/12345")
+
+        Returns:
+            File object with id and url for use in render calls
+
+        Example:
+            file = await files.upload_bytes(image_bytes, "photo.jpg", "image/jpeg")
+        """
+        files = {"file": (filename, content, content_type)}
+        params = {"path": path} if path else None
+        data = await self._http.post_multipart("/api/files/multi", files=files, params=params)
+        return File.from_dict(data)
+
+    async def upload_url(self, url: str, path: str | None = None) -> File:
+        """Upload a file from a URL (async backend processing).
+
+        The backend downloads the file from the URL and uploads it to storage.
+        Returns immediately with state=processing. Use wait_ready() or poll get().
+
+        Args:
+            url: The URL to download the file from
+            path: Optional path prefix for organizing files
+
+        Returns:
+            File object with id and state=processing.
+
+        Example:
+            file = await files.upload_url("https://example.com/image.png")
+            file = await files.wait_ready(file.id)
+        """
+        payload = {"url": url}
+        if path:
+            payload["path"] = path
+        data = await self._http.post("/api/files/url", json=payload)
+        return File.from_dict(data)
+
+    async def upload_b64(
+        self,
+        data: str,
+        filename: str,
+        content_type: str | None = None,
+        path: str | None = None,
+    ) -> File:
+        """Upload a file from base64-encoded data (async backend processing).
+
+        The backend decodes the base64 data and uploads it to storage.
+        Returns immediately with state=processing. Use wait_ready() or poll get().
+
+        Args:
+            data: Base64-encoded file content
+            filename: Filename to use (e.g., "image.jpg")
+            content_type: MIME type (auto-detected from filename if not provided)
+            path: Optional path prefix for organizing files
+
+        Returns:
+            File object with id and state=processing.
+
+        Example:
+            import base64
+            b64_data = base64.b64encode(image_bytes).decode()
+            file = await files.upload_b64(b64_data, "image.png", "image/png")
+            file = await files.wait_ready(file.id)
+        """
+        payload = {"data": data, "filename": filename}
+        if content_type:
+            payload["content_type"] = content_type
+        if path:
+            payload["path"] = path
+        result = await self._http.post("/api/files/b64", json=payload)
+        return File.from_dict(result)
+
+    async def get(self, file_id: str) -> File:
+        """Get file metadata and URL.
+
+        Args:
+            file_id: The file ID
+
+        Returns:
+            File object with url for use in render calls
+        """
+        data = await self._http.get(f"/api/files/{file_id}")
+        return File.from_dict(data)
+
+    async def delete(self, file_id: str) -> dict:
+        """Delete an uploaded file.
+
+        Args:
+            file_id: The file ID to delete
+
+        Returns:
+            {"status": "deleted", "id": "..."}
+        """
+        return await self._http.delete(f"/api/files/{file_id}")
+
+    async def wait_ready(
+        self,
+        file_id: str,
+        timeout: float = 60.0,
+        poll_interval: float = 1.0,
+    ) -> File:
+        """Wait for an async upload to complete.
+
+        Polls the file status until it's done or failed.
+
+        Args:
+            file_id: The file ID to wait for
+            timeout: Maximum time to wait in seconds
+            poll_interval: Time between polls in seconds
+
+        Returns:
+            File object with final state (done or failed)
+
+        Raises:
+            TimeoutError: If file doesn't complete within timeout
+            ValueError: If file upload failed
+
+        Example:
+            file = await files.upload_url("https://example.com/image.png")
+            file = await files.wait_ready(file.id, timeout=30)
+            print(f"Ready: {file.url}")
+        """
+        import time
+        start = time.time()
+        while time.time() - start < timeout:
+            file = await self.get(file_id)
+            if file.is_ready:
+                return file
+            if file.is_failed:
+                raise ValueError(f"File upload failed: {file.error}")
+            await asyncio.sleep(poll_interval)
+        raise TimeoutError(f"File {file_id} did not complete within {timeout}s")