commoncompute 0.1.0__py3-none-any.whl

commoncompute/__init__.py

@@ -0,0 +1,86 @@
+"""Common Compute — official Python SDK.
+
+Thin, typed wrapper around the Common Compute HTTP API. Ships an OpenAI-
+compatible path for drop-in migration plus first-class helpers for the
+native job API. See https://commoncompute.ai/docs for the full reference.
+
+Quickstart::
+
+    import commoncompute as cc
+
+    client = cc.Client(api_key="cc_live_...")
+    print(client.balance())
+
+    # OpenAI-compatible chat
+    reply = client.chat.create(
+        model="qwen-2.5-7b-instruct",
+        messages=[{"role": "user", "content": "hi"}],
+    )
+    print(reply["choices"][0]["message"]["content"])
+
+    # Native job submission
+    job = client.jobs.submit(
+        workload_id="coreml_embed",
+        payload={"inputs": ["hello world"]},
+    )
+    result = client.jobs.wait(job["id"])
+
+Streaming chat::
+
+    for chunk in client.chat.stream(model="qwen-2.5-7b-instruct",
+                                    messages=[{"role": "user", "content": "hi"}]):
+        delta = chunk["choices"][0].get("delta", {}).get("content", "")
+        print(delta, end="", flush=True)
+"""
+
+# MUST come before any submodule imports — _transport.py reads
+# `commoncompute.__version__` at import time for the User-Agent header,
+# and the previous ordering (`__version__` defined at the bottom) made
+# every clean install of the SDK fail with a circular ImportError.
+__version__ = "0.1.0"
+
+from .client import Client, AsyncClient
+from .errors import (
+    CommonComputeError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    InsufficientFundsError,
+    InsufficientCreditsError,  # legacy alias of InsufficientFundsError
+    BadRequestError,
+    ValidationError,
+    UnsupportedFormatError,
+    NetworkError,
+    JobTimeoutError,
+    APIError,
+)
+from .models import Job, Quote, Receipt, TaskResult, AccountTier, SpendSummary
+from .connect import connect, login
+from . import aws_batch  # noqa: E402  (intentional re-export)
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "connect",
+    "login",
+    "CommonComputeError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "InsufficientFundsError",
+    "InsufficientCreditsError",
+    "BadRequestError",
+    "ValidationError",
+    "UnsupportedFormatError",
+    "NetworkError",
+    "JobTimeoutError",
+    "APIError",
+    "Job",
+    "Quote",
+    "Receipt",
+    "TaskResult",
+    "AccountTier",
+    "SpendSummary",
+    "aws_batch",
+    "__version__",
+]

commoncompute/_generated_workloads.py

@@ -0,0 +1,60 @@
+# @generated by packages/workloads/codegen/emit-sdk-workloads.ts — DO NOT EDIT.
+# Regenerate:  npx tsx packages/workloads/codegen/emit-sdk-workloads.ts
+# Source of truth: packages/workloads (the shared catalog). CI fails if this
+# file drifts from the catalog (see tests/unit/workloads-parity.test.ts).
+from __future__ import annotations
+
+# Every workload id in the catalog. Used to decide whether a jobDefinition head
+# names a workload directly vs. a model.
+KNOWN_WORKLOAD_IDS: frozenset[str] = frozenset({
+    "coreml_embed",
+    "whisper_ane",
+    "whisper_subtitle",
+    "accelerate_denoise",
+    "pyannote_diarize",
+    "audio_classify",
+    "avspeech_tts",
+    "apple_translate",
+    "bge_rerank",
+    "nl_langdetect",
+    "nl_ner",
+    "nl_sentiment",
+    "vision_ocr",
+    "vision_bgremove",
+    "vision_aesthetics",
+    "vision_face",
+    "vision_detect",
+    "vision_pose",
+    "vision_barcode",
+    "vision_segment",
+    "coreml_upscale",
+    "vt_transcode",
+    "videotoolbox_heic",
+    "av_thumbnail",
+    "vision_scene",
+    "mlx_image",
+    "xcode_build",
+    "xctest_runner",
+    "mlx_small_rag",
+    "mlx_llm",
+    "mlx_llm_long_ctx",
+    "coreml_vision",
+    "sd_mlx",
+    "mlx_finetune",
+    "pytorch_mps",
+    "blender_metal",
+    "cpu_bench",
+})
+
+# (regex source, workload_id), highest priority first. Compile with re.IGNORECASE.
+IMAGE_PATTERNS: tuple[tuple[str, str], ...] = (
+    ("whisper", "whisper_ane"),
+    ("(embed|sentence-transformer|bge|e5-)", "coreml_embed"),
+    ("(stable-diffusion|sdxl|sd-|sd_)", "sd_mlx"),
+    ("(flux|mlx-image)", "mlx_image"),
+    ("(llama|mistral|qwen|mlx-llm|chat-llm)", "mlx_llm"),
+    ("(ffmpeg|transcode|videotoolbox|vt[-_])", "vt_transcode"),
+    ("(ocr|tesseract|textract)", "vision_ocr"),
+    ("(blender|cycles)", "blender_metal"),
+    ("(pytorch|torch)", "pytorch_mps"),
+)

commoncompute/_transport.py

@@ -0,0 +1,359 @@
+"""Low-level HTTP transport shared by sync + async clients.
+
+Thin wrapper around httpx that:
+- injects ``Authorization: Bearer <api_key>`` and ``User-Agent``
+- injects the optional ``X-CC-Org`` header for multi-workspace accounts
+- re-raises non-2xx responses as typed SDK exceptions
+- parses JSON once and surfaces the request-id for support
+- handles Server-Sent Events streaming (``text/event-stream``)
+
+Kept deliberately small so both ``Client`` and ``AsyncClient`` can share
+the same contract without duplicating retry / parse logic.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import random
+import time
+import uuid
+from typing import Any, AsyncIterator, Iterator, Mapping, Optional
+
+import httpx
+
+from . import __version__
+from .errors import CommonComputeError, NetworkError, _from_status
+
+DEFAULT_BASE_URL = "https://api.commoncompute.ai"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+
+
+def _key_from_config_files() -> Optional[str]:
+    """API-key fallback when CC_API_KEY isn't set.
+
+    Checks ``~/.commoncompute/config`` (documented location; either a bare
+    key or an ``api_key = ...`` line) and the legacy CLI location
+    ``~/.config/commoncompute/credentials``. Never logs the key.
+    """
+    import pathlib
+
+    candidates = [
+        pathlib.Path(os.environ.get("CC_CONFIG_DIR") or (pathlib.Path.home() / ".commoncompute")) / "config",
+        pathlib.Path.home() / ".config" / "commoncompute" / "credentials",
+    ]
+    for path in candidates:
+        try:
+            if not path.exists():
+                continue
+            for line in path.read_text().splitlines():
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                if "=" in line:
+                    k, _, v = line.partition("=")
+                    if k.strip().lower() in ("api_key", "cc_api_key"):
+                        return v.strip().strip('"').strip("'") or None
+                    continue
+                return line
+        except OSError:
+            continue
+    return None
+
+# Transient statuses worth retrying. 503 is retryable EXCEPT when the body
+# carries code=no_capacity — that's the API's deterministic "no provider can
+# run this workload right now" answer; re-submitting burns the server's
+# grace window again for the same outcome.
+_RETRYABLE_STATUSES = {429, 500, 502, 503, 504}
+
+
+def _is_retryable(response: httpx.Response) -> bool:
+    if response.status_code not in _RETRYABLE_STATUSES:
+        return False
+    if response.status_code == 503:
+        body = _parse_body(response)
+        if isinstance(body, dict):
+            err = body.get("error")
+            code = body.get("code") or (err.get("code") if isinstance(err, dict) else None)
+            if code == "no_capacity":
+                return False
+    return True
+
+
+def _retry_delay(attempt: int, response: Optional[httpx.Response]) -> float:
+    if response is not None:
+        ra = response.headers.get("retry-after")
+        if ra:
+            try:
+                return min(max(float(ra), 0.0), 30.0)
+            except ValueError:
+                pass
+    # 0.5s, 1.5s (+ jitter) — bounded so 3 attempts fit a 60s caller budget.
+    return 0.5 * (3**attempt) + random.random() * 0.25
+
+
+def _build_headers(
+    api_key: Optional[str],
+    org: Optional[str],
+    extra: Optional[Mapping[str, str]] = None,
+) -> dict[str, str]:
+    headers: dict[str, str] = {
+        "User-Agent": f"commoncompute-python/{__version__}",
+        "Accept": "application/json",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    if org:
+        headers["X-CC-Org"] = org
+    if extra:
+        for k, v in extra.items():
+            if v is not None:
+                headers[k] = str(v)
+    return headers
+
+
+def _parse_body(response: httpx.Response) -> Any:
+    """Best-effort JSON parse; fall back to raw text for non-JSON bodies."""
+    ct = response.headers.get("content-type", "")
+    if "application/json" in ct or response.text.startswith(("{", "[")):
+        try:
+            return response.json()
+        except (json.JSONDecodeError, ValueError):
+            return {"raw": response.text}
+    return response.text
+
+
+def _raise_for(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    body = _parse_body(response)
+    code = None
+    message = f"HTTP {response.status_code}"
+    if isinstance(body, dict):
+        code = body.get("code") or body.get("error_code")
+        err = body.get("error")
+        if isinstance(err, dict):
+            # OpenAI-shaped error body: {"error": {"message", "type", "code"}}
+            message = err.get("message") or body.get("message") or message
+            code = code or err.get("code")
+        else:
+            message = err or body.get("message") or message
+    request_id = response.headers.get("x-request-id") or response.headers.get("cf-ray")
+    raise _from_status(response.status_code, str(message), code=code, request_id=request_id, body=body)
+
+
+class _BaseTransport:
+    """Shared config between sync and async transports."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        org: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("CC_API_KEY") or _key_from_config_files()
+        if not resolved_key:
+            raise CommonComputeError(
+                "No API key. Run commoncompute.connect() (opens the browser, "
+                "no copy-paste) or `cc login` from a terminal — or pass "
+                "api_key=... / set CC_API_KEY.",
+                status_code=None,
+                code="missing_api_key",
+            )
+        self._api_key = resolved_key
+        self._base_url = (base_url or os.environ.get("CC_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._org = org or os.environ.get("CC_ORG")
+        self._timeout = timeout
+
+    def _url(self, path: str) -> str:
+        if path.startswith(("http://", "https://")):
+            return path
+        if not path.startswith("/"):
+            path = "/" + path
+        return self._base_url + path
+
+
+class SyncTransport(_BaseTransport):
+    """Synchronous HTTP client, used by ``Client``."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = httpx.Client(timeout=self._timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "SyncTransport":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json_body: Any = None,
+        data: Any = None,
+        files: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        hdrs = _build_headers(self._api_key, self._org, headers)
+        # Fresh Idempotency-Key per logical call makes retried POSTs replay
+        # the original submission server-side instead of double-charging.
+        if method.upper() == "POST" and "Idempotency-Key" not in hdrs:
+            hdrs["Idempotency-Key"] = f"idem_{uuid.uuid4()}"
+        # File handles can't be rewound safely after a send — no retries then.
+        attempts = 1 if files is not None else DEFAULT_MAX_RETRIES + 1
+        last_exc: Optional[Exception] = None
+        for attempt in range(attempts):
+            try:
+                resp = self._client.request(
+                    method,
+                    self._url(path),
+                    params=params,
+                    json=json_body,
+                    data=data,
+                    files=files,
+                    headers=hdrs,
+                )
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < attempts - 1:
+                    time.sleep(_retry_delay(attempt, None))
+                    continue
+                raise NetworkError(str(exc), code="network_error") from exc
+            if not resp.is_success and attempt < attempts - 1 and _is_retryable(resp):
+                time.sleep(_retry_delay(attempt, resp))
+                continue
+            _raise_for(resp)
+            return _parse_body(resp)
+        if isinstance(last_exc, httpx.TransportError):
+            raise NetworkError(str(last_exc), code="network_error") from last_exc
+        raise last_exc if last_exc else CommonComputeError("request failed", status_code=None, code="request_failed")
+
+    def stream_sse(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Iterator[dict[str, Any]]:
+        """Yield parsed JSON event payloads from a text/event-stream response."""
+        hdrs = _build_headers(self._api_key, self._org, headers)
+        hdrs["Accept"] = "text/event-stream"
+        with self._client.stream(
+            method,
+            self._url(path),
+            json=json_body,
+            headers=hdrs,
+        ) as resp:
+            if not resp.is_success:
+                resp.read()
+                _raise_for(resp)
+            for line in resp.iter_lines():
+                if not line or not line.startswith("data:"):
+                    continue
+                payload = line[5:].strip()
+                if payload == "[DONE]":
+                    return
+                try:
+                    yield json.loads(payload)
+                except json.JSONDecodeError:
+                    continue
+
+
+class AsyncTransport(_BaseTransport):
+    """Asynchronous HTTP client, used by ``AsyncClient``."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = httpx.AsyncClient(timeout=self._timeout)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncTransport":
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json_body: Any = None,
+        data: Any = None,
+        files: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        hdrs = _build_headers(self._api_key, self._org, headers)
+        if method.upper() == "POST" and "Idempotency-Key" not in hdrs:
+            hdrs["Idempotency-Key"] = f"idem_{uuid.uuid4()}"
+        attempts = 1 if files is not None else DEFAULT_MAX_RETRIES + 1
+        last_exc: Optional[Exception] = None
+        for attempt in range(attempts):
+            try:
+                resp = await self._client.request(
+                    method,
+                    self._url(path),
+                    params=params,
+                    json=json_body,
+                    data=data,
+                    files=files,
+                    headers=hdrs,
+                )
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < attempts - 1:
+                    await asyncio.sleep(_retry_delay(attempt, None))
+                    continue
+                raise NetworkError(str(exc), code="network_error") from exc
+            if not resp.is_success and attempt < attempts - 1 and _is_retryable(resp):
+                await asyncio.sleep(_retry_delay(attempt, resp))
+                continue
+            _raise_for(resp)
+            return _parse_body(resp)
+        if isinstance(last_exc, httpx.TransportError):
+            raise NetworkError(str(last_exc), code="network_error") from last_exc
+        raise last_exc if last_exc else CommonComputeError("request failed", status_code=None, code="request_failed")
+
+    async def stream_sse(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        hdrs = _build_headers(self._api_key, self._org, headers)
+        hdrs["Accept"] = "text/event-stream"
+        async with self._client.stream(
+            method,
+            self._url(path),
+            json=json_body,
+            headers=hdrs,
+        ) as resp:
+            if not resp.is_success:
+                await resp.aread()
+                _raise_for(resp)
+            async for line in resp.aiter_lines():
+                if not line or not line.startswith("data:"):
+                    continue
+                payload = line[5:].strip()
+                if payload == "[DONE]":
+                    return
+                try:
+                    yield json.loads(payload)
+                except json.JSONDecodeError:
+                    continue