Skip to main content
Request and response schemas for model inference. These Pydantic models define the JSON payloads exchanged between clients and a deployed model endpoint (e.g. SageMaker or a local server). Each request/response pair corresponds to a single tile.

​
InferenceMode

Inference modes shared across the server, clients, and pipeline. The values are the on-wire strings (the SageMaker /invocations mode field and the REST endpoint keys), so this enum is the single source of truth for mode identifiers without changing the wire contract. Because it is a StrEnum, members compare, hash, and serialize exactly like their string value, so they are drop-in wherever a mode string was used.

​
coerce_inference_mode

Normalizes a mode or stage argument to an InferenceMode. Accepts an InferenceMode member unchanged, a canonical on-wire string (for example "prediction"), or a legacy short spelling (for example "predict"). A legacy spelling is translated to its canonical member and emits a DeprecationWarning, so the enum is the single source of truth while pre-enum callers keep working.
​
The mode or stage to normalize.
Returns: The corresponding InferenceMode member. Raises:
  • BioptimusValueError - If value is neither a member, a canonical value, nor a known legacy spelling.

​
ModelRequest

Payload sent to the model endpoint for a single tile. The tile image is base64-encoded for JSON transport. Bulk RNA counts can optionally be included for multimodal models. Attributes:
  • image_data - Base64-encoded tile image (PNG).
  • bulk_rna - Optional bulk RNA counts vector.
  • slide_name - Stem of the source slide filename.
  • x - Tile x-coordinate in the slide.
  • y - Tile y-coordinate in the slide.
  • width - Tile width in pixels.
  • height - Tile height in pixels.
  • tissue_ratio - Fraction of tissue in the tile.
  • patch_idx - Index of this tile in the extraction plan.

​
image

Decodes and returns the tile image as PIL.

​
ModelResponse

Payload returned by the model endpoint for a single tile. Carries the model output together with the full tile metadata from the originating request, so that downstream writers can persist everything without needing a separate schema. Attributes:
  • output - Model output vector for this tile.
  • slide_name - Stem of the source slide filename.
  • x - Tile x-coordinate in the slide.
  • y - Tile y-coordinate in the slide.
  • width - Tile width in pixels.
  • height - Tile height in pixels.
  • tissue_ratio - Fraction of tissue in the tile.
  • patch_idx - Index of this tile in the extraction plan.
  • resolution - Extraction resolution (MPP) if available.
  • embedding - The tile embedding, returned alongside output only for the prediction_with_embedding mode (both come from the same forward pass). None for the single-output modes.

​
SageMakerRequest

Extended request for the SageMaker /invocations endpoint. Adds a model_name field so the server can dispatch to the correct model and a mode field to select the scheduler (see InferenceMode).