Skip to content

Peach decorator

The peach decorator lets you run a plain Python function as a Ray remote task on your codops' Peach cluster, straight from your own code (for example a PEACH Lab notebook cell or an exploratory script). You write a normal function, decorate it, and call it. The work runs on the cluster, inside a pre-built Python environment, with the CPU, GPU and memory you ask for.

It lives in pipe_algorithms_lib.compute:

from pipe_algorithms_lib.compute import peach

Quick start

from pipe_algorithms_lib.compute import peach

@peach(num_gpus=0.3, py_env="ml")
def double(x):
    return x * 2

result = double(21)   # runs on the cluster, returns 42

Calling the decorated function is synchronous: it dispatches the task to Ray and blocks until the result comes back. You get the return value directly, not a future, so there is no ray.get(...) to call yourself.

When the task is submitted, the decorator prints the Ray job id and a link to the job in the cluster dashboard, so you can follow its progress and logs:

Ray job submitted | job_id=01000000 | dashboard: https://ray.<codops>.peach.ebu.io/#/jobs/01000000

Choosing the environment

The function runs inside a Python environment that has already been built for your codops. You pick which one with the py_env keyword argument:

Argument Runs the function inside...
py_env="ml" the named shared uv environment (see Python environments)

py_env resolves to a uv project folder on the cluster (/home/ray/uv_projects/<name>). It targets any environment declared under py_environments in your peach.conf.

If you do not pass it, the function runs in the cluster's default environment for the codops.

Listing the available environments

To see which py_env values exist on your codops' cluster, call list_py_envs():

from pipe_algorithms_lib.compute import list_py_envs

list_py_envs()   # -> ["base", "ml", ...]

It returns the names of the uv projects built for your codops; any name in the list can be passed as py_env=. The lookup runs as a lightweight task on the cluster (the environments live on the cluster nodes, not on the machine calling it), so it needs the same CODOPS / RAY_URL setup as the decorator (see Environment variables below).

Installing extra packages on the fly

For quick experiments you can add packages that are not in any pre-built environment:

@peach(num_gpus=0.3, packages=["pandas", "numpy>=2"])
def crunch(df_bytes):
    import pandas as pd
    ...

packages installs the listed dependencies with uv --with at run time.

Exploratory use only

packages cannot be combined with py_env. uv re-resolves the whole environment at run time, which can conflict with the pre-built project environments. For anything heading to production, add the dependency to the relevant environment in your peach.conf instead (see Python environments) and let the image rebuild. Treat packages= as a prototyping shortcut, not a deployment path.

Because packages pulls from the private PyPI registry, the GITLAB_PYPI_REGISTRY_TOKEN environment variable must be set when you use it (see below).

Passing resources to Ray

Any keyword argument other than py_env and packages is passed straight through to @ray.remote. Common ones:

@peach(num_cpus=2, num_gpus=0.5, memory=4 * 1024**3, py_env="ml")
def heavy(x):
    ...

num_cpus, num_gpus and memory are the usual Ray resource requests; Ray uses them to place the task on a suitable node.

Note

Do not pass runtime_env yourself together with py_env or packages: the decorator builds the runtime_env for you from those shorthands, and combining them raises a ValueError.

Environment variables

Variable Purpose
CODOPS Your codops id (for example sesr). Used to find the cluster and to build the dashboard link. Required.
RAY_URL Override the cluster address. Defaults to the in-cluster service for your codops (ray://rayservice-<codops>-grpc.peach-codops-<codops>:10001).
GITLAB_PYPI_REGISTRY_TOKEN Grants uv access to the private PyPI registry. Required only when you use packages=.

Inside PEACH Lab and on the cluster, CODOPS is already set for you. You mainly need RAY_URL when connecting from somewhere outside the cluster, and the registry token only for ad-hoc packages= installs.