gridweave-sdk 0.5.5__tar.gz

gridweave_sdk-0.5.5/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: gridweave-sdk
+Version: 0.5.5
+Summary: Run Python functions and serve models on a GridWeave GPU cluster
+License: Proprietary
+Project-URL: Homepage, https://gridweave.io
+Project-URL: Documentation, https://docs.gridweave.io
+Keywords: gpu,cluster,vllm,inference,compute
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: ==3.12.*
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28
+Requires-Dist: cloudpickle>=3.0
+
+# gridweave-sdk
+
+One Python API for a **heterogeneous GPU cluster** — mix NVIDIA and AMD, size GPUs by the gigabyte, run fractional or multi-GPU, and deploy models you can charge others to call. Works from a script, a notebook, or the REPL.
+
+## Install
+
+```bash
+# First run — the tarball also bundles the onboarding notebook:
+curl -sL https://pub-c48a651bbb2f42988602aa11bb9d9267.r2.dev/tarball/gridweave-sdk.tar.gz | tar xz
+cd gridweave-sdk && python3.12 -m venv .venv && source .venv/bin/activate
+pip install gridweave_sdk-*.whl jupyterlab
+jupyter lab onboarding.ipynb
+
+# Or into an existing env:
+V=$(curl -s https://pub-c48a651bbb2f42988602aa11bb9d9267.r2.dev/tarball/sdk-latest-version.txt)
+pip install https://pub-c48a651bbb2f42988602aa11bb9d9267.r2.dev/tarball/gridweave_sdk-${V}-py3-none-any.whl
+```
+
+**Python 3.12 required** — functions are shipped to the workers with cloudpickle, which won't unpickle across versions.
+
+```python
+import gridweave
+gridweave.auth("YOUR_TOKEN", platform_url="https://platform.gridweave.io")
+gridweave.resources()     # nodes, vendors, and free VRAM
+```
+
+## Run anything, on exactly the hardware you want
+
+Decorate a function, `run()` it — it executes on a worker, streams its stdout back, and returns what it returned. **`vram` is how you ask for GPUs:**
+
+```python
+@gridweave.remote()                # no vram → CPU
+def hello(name):
+    return f"hi {name}"
+
+@gridweave.remote(vram="4GB")      # a GPU with ≥4 GB free
+def matmul():
+    import torch
+    x = torch.randn(4096, 4096, device="cuda")
+    return (x @ x).mean().item()
+
+gridweave.run(matmul)
+```
+
+The cluster is a single pool of mixed hardware, and the same knobs pin any of it:
+
+| Arg | Effect |
+|---|---|
+| `vram="24GB"` | a GPU with ≥24 GB free — **omit for CPU**; ask for more than one GPU has → **multi-GPU** (auto `CUDA_VISIBLE_DEVICES`); two small jobs → **share a GPU** |
+| `vendor="amd"` / `"nvidia"` | pin the GPU brand (default: auto) |
+| `node="hostname"` | pin one machine (from `resources()`) |
+| `paid=True` | run on **provider** hardware (paid credits) vs. the free org pool |
+
+```python
+@gridweave.remote(vram="16GB", vendor="amd")     # a 16 GB AMD GPU
+def on_amd(): ...
+
+@gridweave.remote(vram="100GB")                  # spans several GPUs automatically
+def big(): ...
+```
+
+## Serve a model — and get paid for it
+
+Deploy a model behind an endpoint. vLLM models get an OpenAI-style chat interface; any HTTP container works via `spec=`:
+
+```python
+ep = gridweave.serve(model="Qwen/Qwen2.5-0.5B", vram="4GB", name="qwen")
+ep.chat("Explain quantum computing in one sentence.")
+
+ep = gridweave.serve(spec={"image": "kennethreitz/httpbin", "port": 80,
+                           "actions": {"echo": {"method": "POST", "path": "/post"}}},
+                     name="httpbin")
+ep.call("echo", data={"hello": "cluster"}).json()
+
+gridweave.endpoints(); gridweave.stop("qwen"); gridweave.start("qwen"); gridweave.delete("qwen")
+```
+
+Make it **public and paid** and you run a tiny inference business: callers pay your price (minus a small platform fee), you pay the GPU rental while it's up, and you keep the spread — on your own hardware you keep both sides.
+
+```python
+gridweave.serve(model="Qwen/Qwen2.5-0.5B", vram="4GB", name="qwen-paid",
+                paid=True, public=True, price_per_call=0.01)   # or price_per_1m_input/output
+```
+
+Every vLLM endpoint is also on the **OpenAI-compatible API** (model id `{username}/{name}`), so Open WebUI, curl, or the OpenAI SDK work with no gridweave install:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -d '{"model":"you/qwen","messages":[{"role":"user","content":"hi"}]}' \
+  https://platform.gridweave.io/v1/chat/completions
+```
+
+## Distributed training
+
+`@gridweave.train(gpus=N)` runs your function once per rank with PyTorch Distributed (NCCL/RCCL) already wired up — use `Trainer`/DDP as normal:
+
+```python
+@gridweave.train(gpus=2)
+def finetune():
+    ...                          # build model + Trainer, then trainer.train()
+    import os; return {"rank": int(os.environ.get("RANK", 0))}
+
+gridweave.run(finetune)
+```
+
+## Async, parallel, files, audit trail
+
+```python
+h = gridweave.submit(matmul)                 # non-blocking
+gridweave.status(h); gridweave.get(h)        # poll / block-for-result
+gridweave.gather([gridweave.submit(matmul) for _ in range(10)])   # 10 at once
+
+uri = gridweave.upload("data.csv"); gridweave.download(uri, "data.csv")   # cluster S3
+gridweave.chain(limit=10)                    # your on-chain audit events
+gridweave.chain_rpc("status")                # or verify the ledger yourself — any read-only query
+```
+
+## Learn by doing
+
+`onboarding.ipynb` (in the tarball) runs all of it against a live cluster — CPU / GPU / fractional / multi-GPU jobs, GPT-2 fine-tuning, vLLM + gated + S3 + custom-image serving, the OpenAI API, Open WebUI, paid endpoints, and the audit chain. Each cell is independently re-runnable.
+
+The SDK sends its version on every call; on a **major** mismatch the call is rejected with an "SDK UPDATE REQUIRED" message and the exact `pip install` to run.

gridweave_sdk-0.5.5/README.md

@@ -0,0 +1,122 @@
+# gridweave-sdk
+
+One Python API for a **heterogeneous GPU cluster** — mix NVIDIA and AMD, size GPUs by the gigabyte, run fractional or multi-GPU, and deploy models you can charge others to call. Works from a script, a notebook, or the REPL.
+
+## Install
+
+```bash
+# First run — the tarball also bundles the onboarding notebook:
+curl -sL https://pub-c48a651bbb2f42988602aa11bb9d9267.r2.dev/tarball/gridweave-sdk.tar.gz | tar xz
+cd gridweave-sdk && python3.12 -m venv .venv && source .venv/bin/activate
+pip install gridweave_sdk-*.whl jupyterlab
+jupyter lab onboarding.ipynb
+
+# Or into an existing env:
+V=$(curl -s https://pub-c48a651bbb2f42988602aa11bb9d9267.r2.dev/tarball/sdk-latest-version.txt)
+pip install https://pub-c48a651bbb2f42988602aa11bb9d9267.r2.dev/tarball/gridweave_sdk-${V}-py3-none-any.whl
+```
+
+**Python 3.12 required** — functions are shipped to the workers with cloudpickle, which won't unpickle across versions.
+
+```python
+import gridweave
+gridweave.auth("YOUR_TOKEN", platform_url="https://platform.gridweave.io")
+gridweave.resources()     # nodes, vendors, and free VRAM
+```
+
+## Run anything, on exactly the hardware you want
+
+Decorate a function, `run()` it — it executes on a worker, streams its stdout back, and returns what it returned. **`vram` is how you ask for GPUs:**
+
+```python
+@gridweave.remote()                # no vram → CPU
+def hello(name):
+    return f"hi {name}"
+
+@gridweave.remote(vram="4GB")      # a GPU with ≥4 GB free
+def matmul():
+    import torch
+    x = torch.randn(4096, 4096, device="cuda")
+    return (x @ x).mean().item()
+
+gridweave.run(matmul)
+```
+
+The cluster is a single pool of mixed hardware, and the same knobs pin any of it:
+
+| Arg | Effect |
+|---|---|
+| `vram="24GB"` | a GPU with ≥24 GB free — **omit for CPU**; ask for more than one GPU has → **multi-GPU** (auto `CUDA_VISIBLE_DEVICES`); two small jobs → **share a GPU** |
+| `vendor="amd"` / `"nvidia"` | pin the GPU brand (default: auto) |
+| `node="hostname"` | pin one machine (from `resources()`) |
+| `paid=True` | run on **provider** hardware (paid credits) vs. the free org pool |
+
+```python
+@gridweave.remote(vram="16GB", vendor="amd")     # a 16 GB AMD GPU
+def on_amd(): ...
+
+@gridweave.remote(vram="100GB")                  # spans several GPUs automatically
+def big(): ...
+```
+
+## Serve a model — and get paid for it
+
+Deploy a model behind an endpoint. vLLM models get an OpenAI-style chat interface; any HTTP container works via `spec=`:
+
+```python
+ep = gridweave.serve(model="Qwen/Qwen2.5-0.5B", vram="4GB", name="qwen")
+ep.chat("Explain quantum computing in one sentence.")
+
+ep = gridweave.serve(spec={"image": "kennethreitz/httpbin", "port": 80,
+                           "actions": {"echo": {"method": "POST", "path": "/post"}}},
+                     name="httpbin")
+ep.call("echo", data={"hello": "cluster"}).json()
+
+gridweave.endpoints(); gridweave.stop("qwen"); gridweave.start("qwen"); gridweave.delete("qwen")
+```
+
+Make it **public and paid** and you run a tiny inference business: callers pay your price (minus a small platform fee), you pay the GPU rental while it's up, and you keep the spread — on your own hardware you keep both sides.
+
+```python
+gridweave.serve(model="Qwen/Qwen2.5-0.5B", vram="4GB", name="qwen-paid",
+                paid=True, public=True, price_per_call=0.01)   # or price_per_1m_input/output
+```
+
+Every vLLM endpoint is also on the **OpenAI-compatible API** (model id `{username}/{name}`), so Open WebUI, curl, or the OpenAI SDK work with no gridweave install:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -d '{"model":"you/qwen","messages":[{"role":"user","content":"hi"}]}' \
+  https://platform.gridweave.io/v1/chat/completions
+```
+
+## Distributed training
+
+`@gridweave.train(gpus=N)` runs your function once per rank with PyTorch Distributed (NCCL/RCCL) already wired up — use `Trainer`/DDP as normal:
+
+```python
+@gridweave.train(gpus=2)
+def finetune():
+    ...                          # build model + Trainer, then trainer.train()
+    import os; return {"rank": int(os.environ.get("RANK", 0))}
+
+gridweave.run(finetune)
+```
+
+## Async, parallel, files, audit trail
+
+```python
+h = gridweave.submit(matmul)                 # non-blocking
+gridweave.status(h); gridweave.get(h)        # poll / block-for-result
+gridweave.gather([gridweave.submit(matmul) for _ in range(10)])   # 10 at once
+
+uri = gridweave.upload("data.csv"); gridweave.download(uri, "data.csv")   # cluster S3
+gridweave.chain(limit=10)                    # your on-chain audit events
+gridweave.chain_rpc("status")                # or verify the ledger yourself — any read-only query
+```
+
+## Learn by doing
+
+`onboarding.ipynb` (in the tarball) runs all of it against a live cluster — CPU / GPU / fractional / multi-GPU jobs, GPT-2 fine-tuning, vLLM + gated + S3 + custom-image serving, the OpenAI API, Open WebUI, paid endpoints, and the audit chain. Each cell is independently re-runnable.
+
+The SDK sends its version on every call; on a **major** mismatch the call is rejected with an "SDK UPDATE REQUIRED" message and the exact `pip install` to run.

gridweave_sdk-0.5.5/__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_sdk-0.5.5/__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_sdk-0.5.5/_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_sdk-0.5.5/_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)