> ## 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.

# types

Model specification types.

Defines `ModelSpec` which encapsulates a model's identity, input tile requirements, normalisation parameters, output contract, and compute hints.

Reuses `TileSpec` for tile geometry so the same spec drives both the extraction pipeline and the model's expectations.

**Example:**

```python theme={null}
from bioptimus.extraction.wsi.types import TileSpec
from bioptimus.io.wsi.types import MPP, MeasurementUnit
from bioptimus.models.types import ModelSpec

spec = ModelSpec(
    model_name="h1",
    version="1.0.0",
    tile_spec=TileSpec(
        size=(224, 224),
        stride=(224, 224),
        resolution=MPP(0.5),
        unit=MeasurementUnit.PIXELS,
    ),
    embedding_dim=1536,
    output_type="cls+patch_mean",
    num_prefix_tokens=1,
    patch_size=14,
    mean=(0.707, 0.579, 0.704),
    std=(0.212, 0.230, 0.178),
    weights_source="bioptimus/H1",
)
```

## Models

```python theme={null}
class Models(str, Enum)
```

Known model identifiers.

Values correspond to the `model_name` field in each YAML config under `bioptimus/models/configs/`.

## ModelSpec

```python theme={null}
@dataclass(frozen=True)
class ModelSpec()
```

Describes a backbone model's input and output contract.

Combines tile extraction requirements (via `TileSpec`) with preprocessing, architecture, and output metadata so that data pipelines can prepare inputs and interpret outputs correctly without manual configuration.

This is **framework-agnostic** — it contains only plain Python types and can be consumed by PyTorch, TensorFlow, JAX, or any other framework.

Groups: **Identity & provenance** — who is this model? **Input / preprocessing** — what does the model expect? **Architecture** — structural hints for generic code. **Output** — how to interpret the raw model output. **Compute** — precision & hardware hints.

<ParamField body="model_name">
  Unique identifier / registry key (e.g. `"h1"`).
</ParamField>

<ParamField body="version">
  Model version string (e.g. `"1.0.0"`).  Ensures embeddings extracted with v1 are not mixed with v2.
</ParamField>

<ParamField body="weights_source">
  HuggingFace repo, URL, or local path to weights (e.g. `"bioptimus/H1"`).  `None` = no auto-download.
</ParamField>

<ParamField body="license">
  SPDX identifier or short description (e.g. `"proprietary"`, `"apache-2.0"`).
</ParamField>

<ParamField body="tile_spec">
  Tile geometry the model expects (size, stride, resolution, measurement unit).  Directly reusable by `TileExtractor`.
</ParamField>

<ParamField body="num_channels">
  Number of input image channels (default 3 for RGB).
</ParamField>

<ParamField body="mean">
  Per-channel normalisation mean (channel order matches input).
</ParamField>

<ParamField body="std">
  Per-channel normalisation std.
</ParamField>

<ParamField body="interpolation">
  Resize interpolation mode string (e.g. `"bicubic"`, `"bilinear"`).
</ParamField>

<ParamField body="antialias">
  Whether the resize operation should use antialiasing.
</ParamField>

<ParamField body="color_space">
  Expected colour space of the input image (`"RGB"`, `"BGR"`, `"HED"`).
</ParamField>

<ParamField body="stain_normalization">
  Stain normalisation method applied *before* the model, or `None` for no stain normalisation. (e.g. `"macenko"`, `"reinhard"`, `"vahadane"`).
</ParamField>

<ParamField body="architecture">
  Architecture family (`"vit"`, `"swin"`, `"resnet"`, `"convnext"`, …).
</ParamField>

<ParamField body="patch_size">
  ViT patch size (e.g. 14, 16).  Determines the number of output tokens = `(tile_size / patch_size)²`.  `None` for non-ViT architectures.
</ParamField>

<ParamField body="num_prefix_tokens">
  Number of non-spatial prefix tokens before patch tokens in the output sequence (CLS, register tokens, …).  E.g. DINOv2-reg = 5, most ViTs = 1.
</ParamField>

<ParamField body="embedding_dim">
  Dimensionality of the *final* output feature vector (after any post-processing like CLS + mean pooling).
</ParamField>

<ParamField body="output_type">
  How the raw model output is consumed: `"cls"` | `"patch_mean"` | `"cls+patch_mean"` | `"dense"` | `"token_sequence"`.
</ParamField>

<ParamField body="output_spatial_dims">
  For dense / segmentation models that output a spatial feature map, e.g. `(16, 16)`.  `None` for pooled-output models.
</ParamField>

<ParamField body="precision">
  Recommended inference precision (`"fp32"`, `"fp16"`, `"bf16"`).
</ParamField>