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, task="my_job")
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 at most one of these keyword arguments:

Argument Runs the function inside...
task="my_job" the named task's pre-installed environment
endpoint_component="trending_programs__main_v2" the named endpoint component's environment
py_env="ml" the named shared uv environment (see Python environments)

task, endpoint_component and py_env all resolve to the same thing under the hood: a uv project folder on the cluster (/home/ray/uv_projects/<name>). They are three names for the same mechanism, kept separate so the call reads naturally depending on what you are pointing at. py_env is the most general: it targets any environment declared under py_environments in your peach.conf.

If you pass none of them, the function runs in the cluster's default environment for the codops.

Note

task, endpoint_component and py_env are mutually exclusive. Passing more than one raises a ValueError.

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 task, endpoint_component or 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 task, endpoint_component, 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, task="heavy_job")
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 task, endpoint_component, 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.