Handler

A worker file registers one warmup and one handler.

Warmup

import surfra

@surfra.warmup
def load():
    ...

Warmup runs once in the process, before the worker accepts requests. Load weights here. Concurrent workers in the same process share that load.

One request

With the default batch size, the handler receives a single surfra.Request.

@surfra.handler
def predict(request: surfra.Request):
    return {"echo": request.input}

Field	Meaning
request.input	JSON object from the caller
request.progress(fraction, message="")	Record progress for this request
surfra.progress(fraction, message="")	Same call, using the request that is running now

fraction is between 0 and 1.

Schemas

Optional JSON Schemas are stored with the handler and shown in the workflow editor. They do not reject a payload by themselves.

@surfra.handler(
    input_schema={"type": "object", "properties": {"prompt": {"type": "string"}}},
    output_schema={"type": "object"},
)
def predict(request: surfra.Request):
    return {"text": request.input["prompt"]}

A file that registers a second @surfra.handler raises RuntimeError.