gridweave-sdk 0.5.5__py3-none-any.whl

gridweave/__init__.py

@@ -0,0 +1,36 @@
+"""gridweave — client SDK for submitting jobs to the compute cluster."""
+import logging as _logging
+from pathlib import Path as _Path
+
+_logging.getLogger("gridweave").addHandler(_logging.NullHandler())
+
+_version_file = _Path(__file__).resolve().parent.parent / "VERSION_SDK"
+if _version_file.exists():
+    __version__ = _version_file.read_text().strip()
+else:
+    try:
+        from importlib.metadata import version as _pkg_version
+        __version__ = _pkg_version("gridweave-sdk")
+    except Exception:
+        __version__ = "0.0.0"
+
+from .auth import auth
+from .remote import remote
+from .train import train
+from .execution import run, submit, get, gather, logs, status, cancel
+from .images import build_env, run_image, submit_image
+from .storage import upload, download, list_files
+from .resources import resources
+from .serve import serve, endpoint, endpoints, stop, start, delete
+from .chain import chain, chain_rpc
+from .registry import registry_login, registry_status, registry_logout, push_image, delete_image
+
+__all__ = [
+    "auth", "remote", "train", "run", "submit", "get", "gather", "logs", "status",
+    "cancel", "run_image", "submit_image", "build_env",
+    "upload", "download", "list_files", "resources",
+    "serve", "endpoint", "endpoints", "stop", "start", "delete",
+    "chain", "chain_rpc",
+    "registry_login", "registry_status", "registry_logout", "push_image",
+    "delete_image",
+]

gridweave/__main__.py

@@ -0,0 +1,8 @@
+"""python -m client_sdk — quick version/health check."""
+
+from . import __version__
+from .auth import get_platform_url
+
+if __name__ == "__main__":
+    print(f"gridweave client v{__version__}")
+    print(f"platform: {get_platform_url()}")

gridweave/_http.py

@@ -0,0 +1,31 @@
+"""Thin wrappers over the shared pooled client (auth.client()).
+
+SDK modules import this as `http` — one connection pool for every call,
+with connect-level retries, instead of a fresh TCP+TLS handshake per
+request."""
+
+from .auth import client
+
+
+def get(url, **kwargs):
+    return client().get(url, **kwargs)
+
+
+def post(url, **kwargs):
+    return client().post(url, **kwargs)
+
+
+def put(url, **kwargs):
+    return client().put(url, **kwargs)
+
+
+def delete(url, **kwargs):
+    return client().delete(url, **kwargs)
+
+
+def head(url, **kwargs):
+    return client().head(url, **kwargs)
+
+
+def stream(method, url, **kwargs):
+    return client().stream(method, url, **kwargs)

gridweave/_validation.py

@@ -0,0 +1,270 @@
+"""Client-side input validation — fail fast with actionable messages
+instead of late, opaque server-side errors."""
+
+import os
+import re
+
+MAX_PAYLOAD_BYTES = int(os.environ.get("GRIDWEAVE_MAX_PAYLOAD_BYTES",
+                                       str(10 * 1024 * 1024)))
+
+_VRAM_RE = re.compile(r"^\d+(\.\d+)?\s*(GB|MB)?$", re.IGNORECASE)
+_NAME_RE = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
+_MODEL_RE = re.compile(r"^[\w.\-]+/[\w.\-]+$")
+VALID_VENDORS = {"", "auto", "nvidia", "amd"}
+MAX_VRAM_GB = 2048
+MAX_GPUS = 32
+MAX_CPUS = 1024
+MAX_RAM_GB = 4096
+# Package specs for per-job environments: torch==2.4, pkg[extra]>=1,
+# conda-forge::ffmpeg. No shell metacharacters (;|&$`…) by construction —
+# these specs end up on an installer command line.
+_PKG_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._\-\[\],=<>!~ :]*$")
+MAX_ENV_PKGS = 100
+MAX_PKG_LEN = 200
+
+
+def validate_vram(vram: str) -> str:
+    """Accepts '24GB', '500MB', or a bare number of GB. Returns it stripped."""
+    if not vram:
+        return ""
+    v = str(vram).strip()
+    if not _VRAM_RE.match(v):
+        raise ValueError(
+            f"Invalid vram {vram!r}: expected a number with GB/MB suffix, e.g. '24GB'")
+    digits = re.sub(r"(?i)\s*(GB|MB)$", "", v)
+    gb = float(digits) / 1024 if v.upper().endswith("MB") else float(digits)
+    if not 0 < gb <= MAX_VRAM_GB:
+        raise ValueError(f"Invalid vram {vram!r}: must be between 0 and {MAX_VRAM_GB}GB")
+    return v
+
+
+def validate_gpus(gpus: int) -> int:
+    if not isinstance(gpus, int) or isinstance(gpus, bool) or not 1 <= gpus <= MAX_GPUS:
+        raise ValueError(f"Invalid gpus {gpus!r}: must be an integer between 1 and {MAX_GPUS}")
+    return gpus
+
+
+def validate_cpu(cpu: int) -> int:
+    """Host CPUs to book for a no-vram (CPU-lane) job."""
+    if not isinstance(cpu, int) or isinstance(cpu, bool) or not 1 <= cpu <= MAX_CPUS:
+        raise ValueError(f"Invalid cpu {cpu!r}: must be an integer between 1 and {MAX_CPUS}")
+    return cpu
+
+
+def validate_pkg_list(pkgs, kind: str = "pip") -> list:
+    """Package list for a per-job environment (pip= / conda=)."""
+    if not pkgs:
+        return []
+    if not isinstance(pkgs, (list, tuple)):
+        raise ValueError(
+            f"Invalid {kind} {pkgs!r}: expected a list of package specs, "
+            f"e.g. {kind}=[\"pandas>=2\", \"pyarrow\"]")
+    if len(pkgs) > MAX_ENV_PKGS:
+        raise ValueError(
+            f"Invalid {kind}: {len(pkgs)} packages exceeds the maximum of "
+            f"{MAX_ENV_PKGS} — bake large environments into an image instead")
+    for p in pkgs:
+        if not isinstance(p, str) or not p.strip():
+            raise ValueError(
+                f"Invalid {kind} entry {p!r}: expected a non-empty string")
+        if len(p) > MAX_PKG_LEN or not _PKG_RE.match(p):
+            raise ValueError(
+                f"Invalid {kind} entry {p!r}: not a valid package spec "
+                f"(letters, digits, ._-[],=<>!~: only)")
+    return list(pkgs)
+
+
+def validate_ram(ram: str) -> str:
+    """Host RAM to book for a no-vram (CPU-lane) job.
+    Accepts '8GB', '512MB', or a bare number of GB. Returns it stripped."""
+    if not ram:
+        return ""
+    v = str(ram).strip()
+    if not _VRAM_RE.match(v):
+        raise ValueError(
+            f"Invalid ram {ram!r}: expected a number with GB/MB suffix, e.g. '8GB'")
+    digits = re.sub(r"(?i)\s*(GB|MB)$", "", v)
+    gb = float(digits) / 1024 if v.upper().endswith("MB") else float(digits)
+    if not 0 < gb <= MAX_RAM_GB:
+        raise ValueError(f"Invalid ram {ram!r}: must be between 0 and {MAX_RAM_GB}GB")
+    return v
+
+
+def normalize_vendor(vendor: str) -> str:
+    v = (vendor or "").strip().lower()
+    if v not in VALID_VENDORS:
+        raise ValueError(
+            f"Invalid vendor {vendor!r}: must be one of 'nvidia', 'amd', 'auto', or ''")
+    return "" if v == "auto" else v
+
+
+def validate_endpoint_name(name: str) -> str:
+    """Endpoint names become k8s labels: ≤63 chars of [a-z0-9-], starting
+    and ending alphanumeric."""
+    if not name or len(name) > 63 or not _NAME_RE.match(name):
+        raise ValueError(
+            f"Invalid endpoint name {name!r}: up to 63 lowercase letters, "
+            f"digits, or hyphens, starting and ending with a letter or digit")
+    return name
+
+
+def validate_model(model: str) -> str:
+    """A vLLM model source: either a HuggingFace 'owner/repo' name or an
+    s3:// URI to model weights the gateway downloads at deploy time."""
+    m = model or ""
+    if m.startswith("s3://"):
+        return validate_s3_uri(m)
+    if not _MODEL_RE.match(m):
+        raise ValueError(
+            f"Invalid model {model!r}: expected HuggingFace 'owner/repo' format "
+            f"or an s3:// model URI")
+    return model
+
+
+def check_payload_size(num_bytes: int, what: str = "payload") -> None:
+    if num_bytes > MAX_PAYLOAD_BYTES:
+        raise ValueError(
+            f"{what} is {num_bytes / 1024 / 1024:.1f}MB — exceeds the "
+            f"{MAX_PAYLOAD_BYTES / 1024 / 1024:.0f}MB limit. Upload large data "
+            f"with gridweave.storage.upload() and load it inside the function "
+            f"(set GRIDWEAVE_MAX_PAYLOAD_BYTES to override).")
+
+
+def validate_job_id(job_id: str) -> str:
+    if not job_id or not str(job_id).strip():
+        raise ValueError("Empty job_id — the handle is not a valid job reference")
+    return job_id
+
+
+def validate_s3_uri(uri: str) -> str:
+    if not (uri or "").startswith("s3://"):
+        raise ValueError(f"Invalid storage uri {uri!r}: must start with 's3://'")
+    return uri
+
+
+# Characters that would let a spec.image string break out into the shell or
+# carry whitespace a container reference can never contain. A valid image ref
+# is just registry/name:tag@digest — none of these belong in it.
+_IMAGE_BAD_CHARS = ";|&$`<>()\\'\" \t\n\r"
+
+
+def validate_image(image: str) -> str:
+    """Container image reference for a custom spec, e.g. 'org/name:tag'.
+    Rejected fast so a typo or injection never reaches the deploy (where it
+    would otherwise surface late as an ImagePullBackOff)."""
+    if not image or not str(image).strip():
+        raise ValueError(
+            "Invalid spec.image: a container image is required, e.g. 'org/name:tag'")
+    img = str(image).strip()
+    bad = "".join(sorted({c for c in img if c in _IMAGE_BAD_CHARS}))
+    if bad:
+        raise ValueError(
+            f"Invalid spec.image {image!r}: contains disallowed character(s) {bad!r}. "
+            f"Use a plain image reference like 'org/name:tag' "
+            f"(no spaces or shell metacharacters)")
+    return img
+
+
+def validate_port(port: int) -> int:
+    """TCP port the user's container listens on (HTTP-mode spec)."""
+    if not isinstance(port, int) or isinstance(port, bool) or not 1 <= port <= 65535:
+        raise ValueError(
+            f"Invalid spec.port {port!r}: must be an integer between 1 and 65535")
+    return port
+
+
+def validate_spec(spec: dict) -> dict:
+    """Mirror the server's custom-image deploy contract so an unrunnable spec
+    fails here — instantly, with the reason — instead of as a late pod or
+    request-time error. Server requires: 'image', plus either 'port' (HTTP
+    mode) or 'actions' (command mode); command-mode actions need a 'command'."""
+    if not isinstance(spec, dict):
+        raise ValueError(
+            f"Invalid spec: expected a dict (or path to a JSON file), "
+            f"got {type(spec).__name__}")
+
+    validate_image(spec.get("image", ""))
+
+    has_port = "port" in spec
+    has_actions = bool(spec.get("actions"))
+    if not has_port and not has_actions:
+        raise ValueError(
+            "Invalid spec: must include either 'port' (your container's HTTP "
+            "port) or 'actions' (command-mode handlers)")
+    if has_port:
+        validate_port(spec["port"])
+    if "gpus" in spec:
+        validate_gpus(spec["gpus"])
+    if "ram" in spec:
+        validate_ram(spec["ram"])  # becomes the pod's memory limit
+
+    actions = spec.get("actions") or {}
+    if actions and not isinstance(actions, dict):
+        raise ValueError(
+            f"Invalid spec.actions: expected a dict of name -> action, "
+            f"got {type(actions).__name__}")
+    for aname, action in actions.items():
+        if not isinstance(action, dict):
+            raise ValueError(
+                f"Invalid spec.actions[{aname!r}]: expected a dict, "
+                f"got {type(action).__name__}")
+        # In command mode (no port) every action runs a shell command; an
+        # empty command would deploy fine then fail at call time with a 500.
+        if not has_port and not str(action.get("command", "")).strip():
+            raise ValueError(
+                f"Invalid spec.actions[{aname!r}]: command-mode actions require "
+                f"a non-empty 'command', e.g. 'python /app/run.py'")
+    return spec
+
+
+def validate_action(action: str) -> str:
+    """Named action on a custom endpoint — must be non-empty, else the call
+    hits /actions/ and 404s late."""
+    if not action or not str(action).strip():
+        raise ValueError("Empty action name — pass the action to call, e.g. ep.call('fold', ...)")
+    return action
+
+
+def validate_local_file(local_path: str) -> str:
+    """A readable local file must exist before we try to upload it — fail
+    here with a clear message instead of a late open() error mid-call."""
+    if not local_path or not str(local_path).strip():
+        raise ValueError("upload() requires a local file path")
+    if not os.path.isfile(local_path):
+        raise ValueError(f"No such file to upload: {local_path!r}")
+    return local_path
+
+
+def _check_price(label: str, value) -> None:
+    if value is None:
+        return
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0:
+        raise ValueError(f"Invalid {label} {value!r}: must be a number >= 0")
+
+
+def validate_pricing(paid: bool, model: str,
+                     price_per_call=None,
+                     price_per_1m_input=None,
+                     price_per_1m_output=None) -> None:
+    """Validate deployer-set endpoint call pricing for serve(). Pricing applies
+    only to paid endpoints; per-call and per-token are mutually exclusive; and
+    per-token pricing is vLLM-only (custom images have no token concept)."""
+    per_call = price_per_call is not None
+    per_token = price_per_1m_input is not None or price_per_1m_output is not None
+    if not per_call and not per_token:
+        return
+    if not paid:
+        raise ValueError(
+            "Endpoint pricing applies only to paid endpoints — pass paid=True "
+            "(free/org endpoints are auto-priced)")
+    if per_call and per_token:
+        raise ValueError(
+            "Set either price_per_call or per-token pricing "
+            "(price_per_1m_input / price_per_1m_output), not both")
+    if per_token and not model:
+        raise ValueError(
+            "Per-token pricing (price_per_1m_*) is vLLM-only — set model=..., "
+            "or use price_per_call for a custom-image endpoint")
+    _check_price("price_per_call", price_per_call)
+    _check_price("price_per_1m_input", price_per_1m_input)
+    _check_price("price_per_1m_output", price_per_1m_output)

gridweave/auth.py

@@ -0,0 +1,80 @@
+"""Authentication — stores token for all subsequent API calls."""
+
+import os
+import sys
+
+import httpx
+
+_token: str | None = None
+_platform_url: str = os.environ.get("PLATFORM_URL", "http://localhost:8100")
+_user_id: str | None = None
+_client: httpx.Client | None = None
+
+
+def auth(token: str, platform_url: str | None = None):
+    """Set the auth token. Optionally override platform URL."""
+    global _token, _platform_url, _user_id
+    if not token or not str(token).strip():
+        raise ValueError("auth() requires a non-empty token")
+    _token = str(token).strip()
+    _user_id = None
+    if platform_url:
+        _platform_url = platform_url
+
+
+def client() -> httpx.Client:
+    """Shared pooled HTTP client — one connection pool for all SDK calls
+    (each call used to open a fresh TCP+TLS connection), with transparent
+    retries on connect failures."""
+    global _client
+    if _client is None:
+        _client = httpx.Client(
+            timeout=30,
+            transport=httpx.HTTPTransport(retries=3),
+            limits=httpx.Limits(max_connections=20, max_keepalive_connections=10),
+        )
+    return _client
+
+
+def get_token() -> str:
+    if not _token:
+        raise RuntimeError("Not authenticated. Call gridweave.auth('your-token') first.")
+    return _token
+
+
+def get_platform_url() -> str:
+    return _platform_url
+
+
+def _headers() -> dict:
+    try:
+        from . import __version__
+    except ImportError:
+        __version__ = "0.0.0"
+    return {
+        "Authorization": f"Bearer {get_token()}",
+        "X-SDK-Version": __version__,
+        # Pickled functions carry CPython bytecode (valid within one minor
+        # version only) — the server rejects submits from a mismatched
+        # Python with an actionable error instead of a worker segfault.
+        "X-Python-Version": f"{sys.version_info[0]}.{sys.version_info[1]}",
+    }
+
+
+def _raise_for_status(resp: httpx.Response) -> None:
+    """Like httpx's built-in, but surfaces the server's error detail in the
+    exception message so notebook users see e.g. 'Insufficient credits' instead
+    of 'Client error 400 Bad Request'."""
+    if resp.is_success:
+        return
+    try:
+        body = resp.json()
+        detail = body.get("detail", body) if isinstance(body, dict) else body
+    except Exception:
+        detail = resp.text or "(no body)"
+    if resp.status_code == 426:
+        raise RuntimeError(f"\n\n{'='*60}\n  SDK UPDATE REQUIRED\n{'='*60}\n  {detail}\n{'='*60}\n")
+    raise httpx.HTTPStatusError(
+        f"{resp.status_code} {resp.reason_phrase}: {detail}",
+        request=resp.request, response=resp,
+    )

gridweave/chain.py

@@ -0,0 +1,29 @@
+"""Chain — read the on-chain audit log and run raw read-only chain queries.
+
+The cluster anchors every credit/job/endpoint event on a private chain
+(tamper-evident audit trail). These helpers let you read it — and verify it
+yourself with arbitrary read-only RPC queries.
+"""
+
+from .auth import get_platform_url, _headers, _raise_for_status
+from . import _http as http
+
+
+def chain(limit: int = 50) -> list[dict]:
+    """Recent on-chain audit events, newest first."""
+    resp = http.get(f"{get_platform_url()}/v1/chain/events",
+                    params={"limit": limit}, headers=_headers(), timeout=15)
+    _raise_for_status(resp)
+    return resp.json()
+
+
+def chain_rpc(method: str, params: dict | None = None) -> dict:
+    """Run a READ-ONLY chain (CometBFT) RPC query and return the raw result —
+    e.g. `chain_rpc("status")`, `chain_rpc("tx_search", {"query": "tx.height >= 1"})`,
+    `chain_rpc("abci_query", {"data": "<key>"})`. Writes are not allowed; this is
+    for inspecting and independently verifying the audit log."""
+    resp = http.post(f"{get_platform_url()}/v1/chain/rpc",
+                     json={"method": method, "params": params or {}},
+                     headers=_headers(), timeout=15)
+    _raise_for_status(resp)
+    return resp.json()