Pool & compute

skyward.Compute(*specs, name=None, options=_DEFAULT_OPTIONS, daemon=False, **kwargs)

Single-pool convenience: creates a Session and provisions one pool.

Three calling conventions (mutually exclusive):

• Named pool: sky.Compute(name="train") — loads from skyward.toml. When daemon = true, connects to the background daemon (auto-spawning if needed).
• Flat kwargs: sky.Compute(provider=sky.AWS(), ...) — assembles a single Spec from keyword arguments.
• Explicit specs: sky.Compute(Spec(...), Spec(...)) — multi-provider fallback.

When daemon=True, routes through the background daemon instead of creating a full Session. The daemon is auto-spawned if not already running. A fingerprint is computed from the spec to identify the pool across script runs.

Parameters:

Name	Type	Description	Default
*specs	Spec	One or more Spec objects. For multi-provider fallback, pass multiple specs. Mutually exclusive with flat kwargs.	()
name	str | None	Pool name from skyward.toml. Mutually exclusive with specs and kwargs.	None
options	Options	Operational tuning (timeouts, retries, autoscaling, session settings). Defaults are sensible for most workloads.	_DEFAULT_OPTIONS
daemon	bool	When True, dispatch through the background daemon instead of creating an inline Session. The daemon is auto-spawned if not already running.	False
**kwargs	Unpack[SpecKwargs]	Flat keyword arguments matching Spec fields. Assembled into a single Spec when no positional specs are given.	{}

Yields:

Type	Description
Pool	A fully provisioned pool ready for task dispatch.

Examples:

>>> with sky.Compute(provider=sky.AWS(), accelerator="A100", nodes=4) as pool:
...     result = train(data) >> pool

>>> with sky.Compute(
...     sky.Spec(provider=sky.VastAI(), accelerator="A100"),
...     sky.Spec(provider=sky.AWS(), accelerator="A100"),
... ) as pool:
...     result = train(data) >> pool

>>> with sky.Compute(name="train") as pool:
...     result = train(data) >> pool

>>> with sky.Compute(provider=sky.AWS(), accelerator="A100", daemon=True) as pool:
...     result = train(data) >> pool

skyward.Spec dataclass

Hardware and environment specification for compute pools.

Pass one or more Spec objects to sky.Compute to define what to provision. For multi-provider fallback, pass multiple specs and set selection in Options.

Parameters:

Name	Type	Description	Default
provider	ProviderConfig	Cloud provider configuration (e.g., sky.AWS(), sky.VastAI()).	required
accelerator	Accelerator | None	GPU type (e.g., "A100", "H100"). None for CPU-only.	None
nodes	NodeSpec	Fixed node count or (min, max) tuple for autoscaling.	1
vcpus	float | None	Minimum vCPUs per node.	None
memory_gb	float | None	Minimum RAM in GB per node.	None
architecture	Architecture | None	CPU architecture filter. None accepts any.	None
allocation	AllocationStrategy	Instance lifecycle strategy.	'spot-if-available'
image	Image	Environment specification (Python version, packages, etc.).	(lambda: Image())()
region	str | None	Cloud region (provider-specific).	None
max_hourly_cost	float | None	Cost cap per node per hour in USD.	None
ttl	int	Auto-shutdown timeout in seconds after pool exits. 0 disables.	600
volumes	list[Volume] | tuple[Volume, ...]	S3/GCS volumes to mount on workers.	()
plugins	list[Plugin] | tuple[Plugin, ...]	Composable plugins to apply to the pool.	()

Examples:

>>> with sky.Compute(
...     sky.Spec(provider=sky.VastAI(), accelerator="A100"),
...     sky.Spec(provider=sky.AWS(), accelerator="A100"),
... ) as compute:
...     result = train(data) >> compute

provider instance-attribute

accelerator = None class-attribute instance-attribute

nodes = 1 class-attribute instance-attribute

vcpus = None class-attribute instance-attribute

memory_gb = None class-attribute instance-attribute

disk_gb = None class-attribute instance-attribute

architecture = None class-attribute instance-attribute

allocation = 'spot-if-available' class-attribute instance-attribute

image = field(default_factory=(lambda: Image())) class-attribute instance-attribute

region = None class-attribute instance-attribute

max_hourly_cost = None class-attribute instance-attribute

ttl = 600 class-attribute instance-attribute

volumes = () class-attribute instance-attribute

plugins = () class-attribute instance-attribute

__init__(provider, accelerator=None, nodes=1, vcpus=None, memory_gb=None, disk_gb=None, architecture=None, allocation='spot-if-available', image=(lambda: Image())(), region=None, max_hourly_cost=None, ttl=600, volumes=(), plugins=())

skyward.SelectionStrategy = Literal['first', 'cheapest']

Multi-spec selection strategy.

• "first" -- use the first spec that has available offers.
• "cheapest" -- compare all specs, pick the lowest price.

skyward.function

Function decorators and pending computation — re-exported from skyward.api.function.

skyward.sky = _Sky() module-attribute

skyward.gather(*pendings, stream=False, ordered=True)

Group pending functions for parallel execution.

Combine multiple PendingFunction instances into a PendingFunctionGroup that runs all tasks concurrently when dispatched with >> pool.

Parameters:

Name	Type	Description	Default
*pendings	PendingFunction[Any]	Pending functions to execute in parallel.	()
stream	bool	If True, yield results as they complete instead of returning a tuple. Default False.	False
ordered	bool	If True, preserve submission order when streaming. Ignored when stream is False. Default True.	True

Returns:

Type	Description
PendingFunctionGroup	A group ready for dispatch.

Examples:

>>> results = gather(task1(), task2(), task3()) >> sky

>>> for result in gather(task1(), task2(), stream=True) >> sky:
...     print(result)

skyward.PendingFunction dataclass

Lazy computation — a frozen snapshot of function + args.

Created by @sky.function decorated calls. Nothing executes until dispatched to a pool via an operator (>>, @, >, &).

Examples:

>>> @sky.function
... def train(data):
...     return model.fit(data)

>>> pending = train(data)  # Returns PendingFunction, doesn't execute
>>> result = pending >> sky  # Execute on one node
>>> results = pending @ sky  # Broadcast to all nodes
>>> result = train(data).with_timeout(600) >> sky  # Override timeout

fn instance-attribute

args instance-attribute

kwargs instance-attribute

timeout = None class-attribute instance-attribute

with_timeout(timeout)

Return a copy with the given execution timeout in seconds.

Parameters:

Name	Type	Description	Default
timeout	float	Maximum execution time in seconds.	required

Returns:

Type	Description
PendingFunction[T]	New instance with the timeout set.

__rshift__(target)

Execute on one node via task() >> pool.

Dispatch this pending function to target for synchronous execution on a single node (round-robin selection).

Parameters:

Name	Type	Description	Default
target	Any	A ComputePool, the sky singleton, or the skyward module.	required

Returns:

Type	Description
T	The remote function's return value.

__gt__(target)

Execute asynchronously via task() > pool.

Dispatch this pending function for non-blocking execution, returning a Future that resolves when the task completes.

Parameters:

Name	Type	Description	Default
target	Any	A ComputePool, the sky singleton, or the skyward module.	required

Returns:

Type	Description
Future[T]	A future that resolves to the remote function's return value.

__matmul__(target)

Broadcast to all nodes via task() @ pool.

Dispatch this pending function to every node in the pool, returning one result per node.

Parameters:

Name	Type	Description	Default
target	Any	A ComputePool, the sky singleton, or the skyward module.	required

Returns:

Type	Description
list[T] | tuple[T, ...]	One result per node in the pool.

__and__(other)

Combine with another pending function via task1() & task2().

Create a PendingFunctionGroup for parallel execution when dispatched with >> pool.

Parameters:

Name	Type	Description	Default
other	PendingFunction[Any] | PendingFunctionGroup	Another pending function or group to combine with.	required

Returns:

Type	Description
PendingFunctionGroup	A group containing both operands.

__init__(fn, args, kwargs, timeout=None)

skyward.PendingFunctionGroup dataclass

Group of pending functions for parallel execution.

Created by chaining & operators or calling sky.gather(). Dispatch the group with >> pool to run all tasks concurrently.

Examples:

>>> group = task1() & task2() & task3()
>>> a, b, c = group >> sky

>>> group = sky.gather(task1(), task2(), task3())
>>> results = group >> sky

items instance-attribute

stream = False class-attribute instance-attribute

ordered = True class-attribute instance-attribute

timeout = None class-attribute instance-attribute

with_timeout(timeout)

Return a copy with the given execution timeout in seconds.

Parameters:

Name	Type	Description	Default
timeout	float	Maximum execution time in seconds, applied to the group.	required

Returns:

Type	Description
PendingFunctionGroup	New instance with the timeout set.

__and__(other)

Append another pending function or group via &.

Parameters:

Name	Type	Description	Default
other	PendingFunction[Any] | PendingFunctionGroup	Another pending function or group to add.	required

Returns:

Type	Description
PendingFunctionGroup	A new group containing all combined items.

__rshift__(target)

Execute all tasks in parallel via group >> pool.

Dispatch every pending function in the group concurrently and return their results as a tuple.

Parameters:

Name	Type	Description	Default
target	Any	A ComputePool, the sky singleton, or the skyward module.	required

Returns:

Type	Description
tuple[Any, ...] | Any	Results from all tasks, one element per pending function.

__len__()

__iter__()

__init__(items, stream=False, ordered=True, timeout=None)

skyward.Offer dataclass

Ephemeral availability + pricing for a specific instance type.

Returned by Provider.offers() and used by the pool to select the best instance for provisioning.

Parameters:

Name	Type	Description	Default
id	str	Provider-specific offer identifier.	required
instance_type	InstanceType	The hardware specification this offer provides.	required
spot_price	float | None	Spot/preemptible price per billing unit, or None if unavailable.	required
on_demand_price	float | None	On-demand price per billing unit, or None if unavailable.	required
billing_unit	Literal['second', 'minute', 'hour']	Granularity of pricing ("second", "minute", or "hour").	required
specific	S	Provider-specific metadata (generic type S).	required

id instance-attribute

instance_type instance-attribute

spot_price instance-attribute

on_demand_price instance-attribute

billing_unit instance-attribute

specific instance-attribute

__init__(id, instance_type, spot_price, on_demand_price, billing_unit, specific)

skyward.InstanceType dataclass

Normalized machine type -- cacheable, provider-agnostic hardware description.

Parameters:

Name	Type	Description	Default
name	str	Provider-specific instance type name (e.g., "p4d.24xlarge").	required
accelerator	Accelerator | None	GPU/accelerator spec, or None for CPU-only instances.	required
vcpus	float	Number of virtual CPUs.	required
memory_gb	float	System RAM in gigabytes.	required
architecture	Architecture	CPU architecture ("x86_64" or "arm64").	required
specific	S	Provider-specific metadata (generic type S).	required

name instance-attribute

accelerator instance-attribute

vcpus instance-attribute

memory_gb instance-attribute

architecture instance-attribute

specific instance-attribute

__init__(name, accelerator, vcpus, memory_gb, architecture, specific)