chalk-remote-call-python 1.3.0

Chalk remote call Python runtime interface client

chalk-remote-call-python

A Python runtime interface for Chalk's RemoteCallService. This package provides a gRPC server backed by a Rust implementation (tonic + PyO3) that lets you define a handler(event, context) function to process incoming Arrow-serialized requests.

The server receives Arrow IPC record batches over a bidirectional gRPC stream, transforms them into a Python dict, invokes your handler, and streams the results back as Arrow IPC.

Requirements

• Python >= 3.10
• Rust toolchain (for building the native extension)
• pyarrow >= 14.0.0

Usage

1. Write a handler

Create a Python module with a handler function:

# my_handler.py
import pyarrow as pa
import pyarrow.compute as pc


def on_startup():
    """Optional -- runs once before the server starts accepting requests."""
    print("Loading model weights...")


def handler(event: dict[str, pa.Array], context: dict) -> pa.Array:
    """Called for each incoming request.

    Args:
        event: dict mapping column names to pyarrow.Array values.
        context: dict with request metadata

    Returns:
        A pyarrow.Array, pyarrow.RecordBatch, pyarrow.Table, list, dict, or scalar.
        The framework auto-converts the result to Arrow IPC for the response.
    """
    return pc.multiply(event["x"], event["y"])


def on_shutdown():
    """Optional -- runs once after the server stops accepting requests."""
    print("Releasing resources...")

2. Start the server

chalk-remote-call --handler my_handler.handler

Or via python -m:

python -m chalk_remote_call --handler my_handler.handler

CLI options

Flag	Env var	Default	Description
--handler		(required)	Dotted path to handler function
--port	CHALK_REMOTE_CALL_PORT	6666	Port to listen on
--host	CHALK_REMOTE_CALL_HOST	[::]	Host to bind to
--workers	CHALK_REMOTE_CALL_WORKERS	10	Tokio runtime worker threads
--on-startup			Dotted path to a startup function
--on-shutdown			Dotted path to a shutdown function
--log-level		INFO	DEBUG, INFO, WARNING, or ERROR

Environment variables

Variable	Description
CHALK_INPUT_ARGS	Comma-separated list of column names (e.g. x,y,z). Renames incoming RecordBatch columns by index. If unset, the original column names are used.

3. Docker image

FROM python:3.11-slim

WORKDIR /app

RUN pip install chalk-remote-call-python

# Copy your handler code
COPY my_handler.py /app

EXPOSE 6666

ENTRYPOINT ["chalk-remote-call"]
CMD ["--handler", "handler.handler"]

Build and run:

docker build -t my-chalk-handler .
docker run -p 6666:6666 -e CHALK_INPUT_ARGS="x,y" my-chalk-handler

Programmatic usage

You can also start the server from Python:

from chalk_remote_call import serve

def handler(event, context):
    return list(event.values())[0]

serve(handler=handler, port=8080)

Local Testing

Use grpcurl to verify the server is running:

# Check health
grpcurl -plaintext localhost:6666 grpc.health.v1.Health/Check

# List services via reflection
grpcurl -plaintext localhost:6666 list

Architecture

The server uses a Rust backend via PyO3:

• tonic — gRPC server with health checking and reflection
• prost — protobuf message handling
• arrow-rs — Arrow IPC validation
• PyO3 — FFI bridge to call Python handler functions

The Rust server runs on a tokio async runtime. When a request arrives, Arrow IPC bytes are passed to Python via PyO3 (spawn_blocking + GIL acquisition), where the handler is invoked. Results are passed back as IPC bytes.

Development

Setup

cd chalk-remote-call-python
uv venv --python 3.11
uv pip install -e ".[dev]"

Running tests

pytest tests/ -v

Rust code

Rust source lives in chalk-remote-call-rs/:

To check the Rust code independently:

PYO3_PYTHON=python3 cargo check --manifest-path chalk-remote-call-rs/chalk-remote-call-server/Cargo.toml