Functions

A function fits batch jobs, background work, and GPU tasks that your code or a person calls. HTTP callers suit an endpoint, and recurring runs a schedule.

Define a function

Save this as reports.py:

from lazycloud import App
from pydantic import BaseModel

app = App("reports")


class SalesSummary(BaseModel):
    sales: int
    total_cents: int


@app.function(cpu=1, memory="256Mi", timeout_seconds=60, retries=0)
def summarize_sales(amounts_cents: list[int]) -> SalesSummary:
    print(f"Summarizing {len(amounts_cents)} sales", flush=True)
    return SalesSummary(sales=len(amounts_cents), total_cents=sum(amounts_cents))

Call it

From the CLI, JSON arguments become Python values:

uv run lazycloud run reports:summarize_sales '[1200, 3500, 800]'

From Python:

from reports import summarize_sales

print(summarize_sales.remote([1200, 3500, 800]))

Both run in a cloud container, stream its logs to your terminal, and return three sales totaling 5500 cents. async_remote() is the async form, and a plain summarize_sales(...) call runs locally. Where a call goes covers previews and deployments.

Process a batch

.map() submits one call per input and yields results in input order. Each tuple holds one call’s arguments:

from reports import summarize_sales

for result in summarize_sales.map([([1200, 3500],), ([800, 900],)]):
    print(result)

A failed call yields None. When every item must succeed before you use the batch, spawn_map() returns each outcome to check:

calls = summarize_sales.spawn_map([([1200, 3500],), ([800, 900],)])
outcomes = [call.result(wait=True) for call in calls]
failed = [outcome.error for outcome in outcomes if not outcome.ok]
if failed:
    raise RuntimeError(failed)
print([outcome.value for outcome in outcomes])

Without an autoscaler the calls run one at a time in one container. An autoscaler lets the function start more containers and run them in parallel:

from lazycloud import Autoscaler


@app.function(
    cpu=1,
    memory="512Mi",
    max_pending_tasks=1000,
    autoscaler=Autoscaler(max_containers=20, tasks_per_container=1),
)
def count_words(text: str) -> int:
    return len(text.split())

A .map() over 1,000 texts now runs on up to 20 containers at once. max_pending_tasks goes up because .map() submits every input at once. See Scaling and the Parquet example.

Submit work in the background

call = summarize_sales.spawn([1200, 3500, 800])
print(call.task_id)
value = call.get()

.spawn() returns a FunctionCall right away, and .get() waits for the value. uv run lazycloud task result <task-id> collects it from anywhere else, and a pending FunctionCall passed to another function arrives as its result. Tasks and logs covers looking calls up by ID.

Arguments and results

Calls from the Python SDK carry any serializable Python value, including NumPy arrays, dataclasses, custom class instances, tuples, and bytes:

import numpy as np
from lazycloud import App, Image

app = App("matrices")
image = Image(python_version="3.12").add_python_packages(["numpy>=2,<3"])


@app.function(image=image)
def matrix() -> np.ndarray:
    return np.arange(6, dtype=np.int64).reshape(2, 3)

The caller needs the same packages and class definitions. Results are unpickled, so they should come from code you trust. HTTP calls, lazycloud run --json, and exported clients need JSON, which Pydantic models and dataclasses convert to. Arguments and results cap at 16 MiB each, so larger output goes in a volume or an artifact.

Function options

Retries and timeouts

timeout_seconds caps one attempt, and retries, 3 by default, adds attempts after a failure. One call can therefore run four times, so writes should be safe to repeat, for example keyed on the input, or retries=0. A RetryPolicy adds backoff:

import urllib.request

from lazycloud import RetryBackoff, RetryPolicy


@app.function(
    retry_policy=RetryPolicy(
        max_attempts=4,
        delay_seconds=2,
        backoff=RetryBackoff.Exponential,
        max_delay_seconds=30,
    ),
)
def fetch_text(url: str) -> str:
    with urllib.request.urlopen(url, timeout=30) as response:
        return response.read().decode("utf-8")

A preempted call retries too, even when its code never failed.

Lifecycle hooks

on_start runs once before a container accepts calls, which suits loading a model or opening a client:

from lazycloud import GpuType

MODEL = {}

def load_model() -> None:
    MODEL["classifier"] = load_classifier()  # your loading code

@app.function(gpu=GpuType.L4, on_start=load_model)
def classify(text: str) -> str:
    return MODEL["classifier"](text)

Per-call hooks are on_running, on_success, on_error, on_retry, on_failure, and on_finish. lazycloud.current_task_id() returns the current call’s ID inside the function or a hook.

Stop and clean up

lazycloud task cancel cancels a pending call and task stop a running one. A deployed function stays callable until stopped:

uv run lazycloud deployment stop summarize_sales
uv run lazycloud deployment delete summarize_sales

stop keeps the definition for deployment start. --prune removes a function deleted from the code.

Shared settings

Images, secrets, volumes, resources, and scaling.

Getting started

Core concepts

CLI reference

Examples

Account

Define a function

Call it

Process a batch

Submit work in the background

Arguments and results

Function options

Retries and timeouts

Lifecycle hooks

Stop and clean up

Shared settings

​Define a function

​Call it

​Process a batch

​Submit work in the background

​Arguments and results

​Function options

​Retries and timeouts

​Lifecycle hooks

​Stop and clean up

​Shared settings

Define a function

Call it

Process a batch

Submit work in the background

Arguments and results

Function options

Retries and timeouts

Lifecycle hooks

Stop and clean up

Shared settings