Compute
API reference for compute configuration, dependencies, and credentials
API reference for compute configuration, dependencies, and credentials.
Public API at a Glance
| Name | Description |
|---|---|
parse_gpu_spec(spec) | Parse GPU specification string |
parse_cpu_spec(spec) | Parse CPU specification string |
Dependencies(python=, apt=, ...) | Python and system dependencies |
Credentials(platform=, env=, ...) | Secrets and API keys |
The current way to declare compute is the @app.function kwargs — gpus="h100:8" strings plus lease/warm/max_concurrency and friends. For hardware guidance, see GPU Specifications. For concept-level explanation, see Compute.
Sub-node shapes and the NVLink domain
A shape with fewer than 8 GPUs (b200:4, h100:4) is placed as a contiguous group within a single node's NVLink domain — the GPUs in a multi-GPU shape are always NVLink-connected, never split across nodes, so a model's own parallelism choices (tp/sp/pp) hold. A shape that needs more than one node's worth of GPUs (e.g. h100:16) spans ceil(gpus / 8) nodes; cross-node communication goes over the inter-node fabric, not NVLink. Whether a sub-node shape shares its node with another tenant depends on your capacity tier — reserved leases pin a whole node; ask your operator if you need a hard isolation guarantee.
parse_gpu_spec()
parse_gpu_spec(spec: str) -> tuple[GPUType, int]Parse a GPU specification string into a type and count.
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
spec | str | required | Format: "type:count" or "type" | GPU specification string |
Returns: tuple[GPUType, int] — GPU type enum member and count.
Raises: ValueError if the spec format is invalid or the GPU type is unknown.
from urun.core.compute import parse_gpu_spec
parse_gpu_spec("h100:8") # -> (GPUType.H100, 8)
parse_gpu_spec("h100") # -> (GPUType.H100, 1)
parse_gpu_spec("a100:4") # -> (GPUType.A100, 4)parse_cpu_spec()
parse_cpu_spec(spec: str | int) -> tuple[int, int]Parse a CPU specification into per-node and total counts.
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
spec | str | int | required | Format: "total", "per_node:total", or int | CPU specification |
Returns: tuple[int, int] — CPUs per node and total CPUs.
Raises: ValueError if the spec format is invalid.
from urun.core.compute import parse_cpu_spec
parse_cpu_spec("128") # -> (128, 128)
parse_cpu_spec("8:128") # -> (8, 128)
parse_cpu_spec(64) # -> (64, 64)Dependencies
@dataclass
class Dependencies:
python: list[str] = field(default_factory=list)
apt: list[str] = field(default_factory=list)
nix: list[str] = field(default_factory=list)
python_version: str = "3.12"
post_install: list[str] = field(default_factory=list)
files: list[str] = field(default_factory=list)Python and system dependency specification. Uses UV for Python packages, apt for system packages, and nix-env for Nix packages.
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
python | list[str] | [] | PEP 508 version specifiers | Python packages (managed by UV) |
apt | list[str] | [] | -- | System packages (managed by apt) |
nix | list[str] | [] | -- | Nix packages (managed by nix-env) |
python_version | str | "3.12" | Valid Python version | Python version requirement |
post_install | list[str] | [] | Shell commands | Commands to run after pip install |
files | list[str] | [] | Paths relative to app.py, individual files (no dirs/globs) | Extra app files to ship past the deploy collector's default heuristic. A declared path that doesn't exist, is absolute, or escapes the app directory fails the deploy loudly. |
Use Dependencies to specify everything your function needs installed in the remote environment. For concept-level guidance, see Dependencies.
from urun.core.dependencies import Dependencies
deps = Dependencies(
python=["torch>=2.7", "transformers>=4.40", "accelerate"],
apt=["ffmpeg", "libgl1-mesa-glx"],
)Builder methods
| Method | Returns | Description |
|---|---|---|
.with_python(*packages) | Dependencies | Add Python packages |
.with_apt(*packages) | Dependencies | Add apt packages |
.with_nix(*packages) | Dependencies | Add Nix packages |
.with_post_install(*commands) | Dependencies | Add post-install commands |
.merge(other) | Dependencies | Merge with another Dependencies |
Credentials
@dataclass
class Credentials:
platform: list[str] = field(default_factory=list)
env: list[str] = field(default_factory=list)
optional_env: list[str] = field(default_factory=list)
env_mapping: dict[str, str] = field(default_factory=dict)Secrets and API key specification. Platform secrets are fetched from the platform's secret manager at runtime. Environment secrets are captured from your local environment at deployment time. There are three sources, all of which land as plain environment variables inside the function:
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
platform | list[str] | [] | -- | Secret names read from platform Vault at runtime |
env | list[str] | [] | required | Env vars captured from your local environment at deploy time (deploy fails if unset) |
optional_env | list[str] | [] | best-effort | Same as env, but silently skipped if unset locally (e.g. an optional HF_TOKEN) |
env_mapping | dict[str, str] | {} | local -> remote | Rename env vars between local and remote |
Use Credentials to declare secrets your function needs at runtime. For concept-level guidance, see Credentials.
from urun.core.credentials import Credentials
creds = Credentials(
platform=["hf-token"],
env=["OPENAI_API_KEY"],
optional_env=["HF_TOKEN"],
)Builder methods
| Method | Returns | Description |
|---|---|---|
.with_platform(*names) | Credentials | Add platform Vault secrets |
.with_env(*vars) | Credentials | Add required local env vars to capture |
.with_optional_env(*vars) | Credentials | Add best-effort local env vars (skipped if unset) |
.with_env_mapping(**mapping) | Credentials | Add env var renaming |
.merge(other) | Credentials | Merge with another Credentials |