bioptimus.runtime.loader

Factory for server-side model handlers. Maps a model name to the correct handler class and loads its exported .pt2 checkpoint. Models with custom forward logic (M-Optimus, tissue segmentation) use a dedicated subclass; all others load as a plain BaseServerModel with the spec resolved from the SDK YAML configs. This factory is the single source of truth for the model registry, shared by the FastAPI server (api) and the SDK in-process backend (InProcessClient).

custom_model_classes

def custom_model_classes() -> dict[str, type[BaseServerModel]]

Returns a copy of the model-name to handler-class registry. Returns: Mapping of model name to its handler class.

build_server_model

def build_server_model(
        model_name: str,
        checkpoint: str | Path,
        device: str = "cuda",
        *,
        assets_root: str | Path | None = None) -> BaseServerModel

Instantiates the model handler for an exported checkpoint.

Registry key (e.g. "h1", "m-optimus", "tissue-seg").

Path to the .pt2 checkpoint file. Its parent directory is used as the model root and its filename as the checkpoint name.

Torch device string ("cuda", "cuda:0", "cpu").

Directory containing gene-set CSVs for M-Optimus. Ignored by models that do not require assets. Defaults to the baked-in container path when omitted.

Returns: A ready-to-use BaseServerModel (or subclass). Raises:

FileNotFoundError - If the checkpoint file does not exist.
KeyError - If the model has no custom handler and no SDK config.

Overview

Get Started

Preprocessing

Workflows

Troubleshooting

Reference

custom_model_classes

build_server_model

​custom_model_classes

​build_server_model

custom_model_classes

build_server_model