localhost:8780 with no auth, as in the
Quickstart. With auth enabled, add
-H "Authorization: Bearer $TOKEN" to every call.
The Python runtime
Nothing is installed at build time. A function built from source can import
the standard library,
pyarrow and its own files under /app. A function
that needs other packages ships as an image.
The image prefix is the server’s RUNTIME_IMAGE_PREFIX (runtimes.imagePrefix
in the Helm chart). ListRuntimes returns the exact image for your server, so
ask it rather than typing the reference:
The protocol
Every Alchemy function speaks the same protocol. For each invocation the supervisor in the microVM starts the entrypoint as a new process and:- writes the input to stdin, then closes it
- takes everything the process writes to stdout as the output
- streams stderr to the invocation’s log
- treats a non-zero exit as a crash, with the exit status and the last 4 KiB of stderr as the error message
Write a JSON handler
This is the runtime’s JSON Schema starter, which the web UI also offers. It reads one value, returns it unchanged and lets any exception exit non-zero:handler.py
handler with your logic. Print diagnostics with
print(..., file=sys.stderr). Anything printed to stdout becomes part of the
output and will likely break the contract.
Write an Arrow handler
An Arrow function receives a batch of rows and returns a batch with the same number of rows in the same order. The platform rejects an output whose row count differs from the input’s.examples/embed/python/handler.py
is a complete one. It reads a batch with an id and a text column and
returns, per row, the cleaned text, its token count and a 64-dimension
embedding. Its shape is the runtime’s Arrow starter:
handler.py
pyarrow:
schemas.py
Deploy from source
A function built from source has no image of its own. Its spec names the runtime image and carries the files. The server stores them as an archive in its artifacts bucket and hosts extract it over the image at/app. The files
are limited to 64 per version and 1 MiB in total, and the runtime runs
handler.py.
Source builds need the server’s
ARTIFACTS_BUCKET and the hosts’ access to
it. Without one, CreateFunction answers failed_precondition: the server has no artifacts bucket, so functions are built from images only.1
Create the function
protocol is required and INVOCATION_PROTOCOL_EXEC is the only one
implemented. timeoutMs, maxConcurrency, retries and resources
are optional on the request: zero takes the server defaults of a 30 s
timeout, no concurrency limit, 1 vCPU and 128 MiB, and an unset
retries takes 2.2
Wait for the build
The first version starts in A
BUILDING. A host pulls the runtime, lays
the files over it, boots the microVM and snapshots it. Only a READY
version can be invoked.FAILED version carries the reason in statusMessage and the tail of
the build output in buildLog.CreateFunctionVersion, or click
New version on the function. The new version becomes current once it is
READY, and the previous one keeps serving until then.
Deploy as an image
Ship an image when the function needs packages the runtime does not have. Build on the runtime so the entrypoint stayspython /app/handler.py. The
embed example’s Dockerfile is two lines:
Dockerfile
RUN pip install ... line for extra packages. Build for the hosts’
architecture and push to a registry the hosts can pull from:
source:
With the local setup, push to
localhost:5001 and reference the image as
192.168.5.2:5001/... in the spec. That is the address the hosts in the
Lima VM reach the compose registry by.Invoke it
POST the input to/functions/<function-id>/invoke with the contract’s
content type. The response body is the output.
Alchemy-Invocation-Id and the version
that ran in Alchemy-Version. A function that exits non-zero answers 500
with its error as JSON, and one that runs past its timeout answers 504. Open
the function’s Invocations tab to read the call’s stderr, or use the
Workbench tab to invoke it from the browser.
The same call is FunctionsService.Invoke on the API, with the input as
bytes. See HTTP invoke for pinning versions,
retries, idempotency keys and async calls.
Next steps
Troubleshooting
Read contract violations, crashes, timeouts and build failures.
Runtimes and builds
How a spec becomes a root filesystem and a snapshot.
Secrets
Give a function credentials without putting them in its spec.
Invocations
Queueing, retries, start kinds and the invocation lifecycle.