> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bioptimus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```python theme={null}
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

```python theme={null}
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.

<ParamField body="model_name">
  Registry key (e.g. `"h1"`, `"m-optimus"`, `"tissue-seg"`).
</ParamField>

<ParamField body="checkpoint">
  Path to the `.pt2` checkpoint file. Its parent directory is used as the model root and its filename as the checkpoint name.
</ParamField>

<ParamField body="device">
  Torch device string (`"cuda"`, `"cuda:0"`, `"cpu"`).
</ParamField>

<ParamField body="assets_root">
  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.
</ParamField>

**Returns**:

A ready-to-use [`BaseServerModel`](/sdk-reference/runtime/server_model#baseservermodel) (or subclass).

**Raises**:

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