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

> The Bioptimus Python SDK — installation and the two ways to use it.

The Bioptimus Python SDK runs whole-slide inference against either an [on-premise server](/deployment/platforms/on-premise) or a [SageMaker endpoint](/deployment/platforms/aws-sagemaker). It handles WSI reading, tiling, tissue masking, bulk-RNA alignment, and concurrent dispatch.

The Bioptimus SDK talks to whichever model is deployed at the endpoint you connect to. `Backbone.available_backbones()` lists the models the Bioptimus SDK *knows how to build* (`h1`, `m-optimus`, `tissue-seg`) — to see what a server actually has loaded, check its [`/ping`](/api-reference/introduction) response.

## Installation

<Tabs>
  <Tab title="PyPI">
    ```bash theme={null}
    pip install bioptimus-sdk
    ```
  </Tab>

  <Tab title="Python Wheel">
    ```bash theme={null}
    pip install bioptimus_sdk-<version>-py3-none-any.whl
    ```
  </Tab>
</Tabs>

## Two ways to use it

<CardGroup cols={2}>
  <Card title="Inference pipeline (recommended)" href="/guides/get-started/inference-pipeline">
    One object configures the whole pipeline. Caches tissue masks, organizes outputs into a workspace, and is reproducible. Best for most users and for cohorts.
  </Card>

  <Card title="Core API (advanced)" href="/guides/workflows/spatial-transcriptomics">
    `Backbone` + `SlideInference` give explicit, per-slide control over the model client, mask provider, and writer.
  </Card>
</CardGroup>

## Connecting to a model

The `Backbone` factory is the low-level client used by both layers.

<Tabs>
  <Tab title="On-premise">
    <CodeGroup>
      ```python H-Optimus theme={null}
      from bioptimus.models.backbones import Backbone
      from bioptimus.models.types import Models

      print(Backbone.available_backbones())   # ['h1', 'm-optimus', 'tissue-seg']
      model = Backbone(Models.H1, backend="remote", base_url="http://localhost:8080")
      ```

      ```python M-Optimus theme={null}
      from bioptimus.models.backbones import Backbone
      from bioptimus.models.types import Models

      print(Backbone.available_backbones())   # ['h1', 'm-optimus', 'tissue-seg']
      model = Backbone(Models.M_OPTIMUS, backend="remote", base_url="http://localhost:8080")
      ```
    </CodeGroup>
  </Tab>

  <Tab title="AWS SageMaker">
    <CodeGroup>
      ```python H-Optimus theme={null}
      from bioptimus.models.backbones import Backbone
      from bioptimus.models.types import Models

      model = Backbone(
          Models.H1, backend="aws",
          endpoint_name="h-optimus", region_name="us-east-1",
      )
      ```

      ```python M-Optimus theme={null}
      from bioptimus.models.backbones import Backbone
      from bioptimus.models.types import Models

      model = Backbone(
          Models.M_OPTIMUS, backend="aws",
          endpoint_name="m-optimus", region_name="us-east-1",
      )
      ```
    </CodeGroup>
  </Tab>
</Tabs>

For M-Optimus, gene sets are fetched from the server automatically (`model.input_gene_names`, `model.output_gene_names`).

<Accordion title="Server not responding? Check /ping first">
  Before constructing a `Backbone` (or an `Inference` pipeline), confirm the on-premise server is reachable:

  ```python theme={null}
  import requests

  requests.get("http://localhost:8080/ping", timeout=5).json()
  # {"status": "ok", "models": ["h1", "tissue-seg"]}
  ```

  If this raises `ConnectionError` / connection refused or times out, nothing is serving at that URL:

  * **Not started** — launch the container, mapping port 8080, then wait for models to load. See [On-premise deployment](/deployment/platforms/on-premise):
    ```bash theme={null}
    docker run -d --name bioptimus-server --gpus all -p 8080:8080 <image> serve
    ```
  * **`503 {"status": "loading"}`** — models are still initialising; wait and retry.
  * **Wrong URL/port** — `base_url` (and the pipeline's `api_url`) must be the server's host and port, with **no** trailing `/ping`.

  For SageMaker there is no `/ping`: confirm the endpoint is `InService` and that `endpoint_name` / `region_name` are correct.
</Accordion>

## Guides

<CardGroup cols={2}>
  <Card title="Inference pipeline" href="/guides/get-started/inference-pipeline">
    One-object pipeline, workspaces, reproducible config.
  </Card>

  <Card title="Cohorts" href="/guides/workflows/cohort">
    Multi-slide cohorts and late-binding bulk RNA.
  </Card>

  <Card title="Spatial transcriptomics" href="/guides/workflows/spatial-transcriptomics">
    M-Optimus gene-expression prediction end to end.
  </Card>

  <Card title="Tile embeddings & PCA" href="/guides/workflows/embeddings-pca">
    Extract embeddings and visualize morphology.
  </Card>

  <Card title="WSI processing" href="/guides/reference/wsi-processing">
    Read slides: levels, MPP, regions, thumbnails.
  </Card>

  <Card title="Visualizing results" href="/guides/get-started/visualizing-results">
    Load Zarr/HDF5/NPZ and overlay genes and masks.
  </Card>
</CardGroup>

## Output formats

| Format              | Extension | Notes                                      |
| ------------------- | --------- | ------------------------------------------ |
| `OutputFormat.ZARR` | `.zarr`   | Default. Directory store, memory-efficient |
| `OutputFormat.HDF5` | `.h5`     | Single file, memory-efficient              |
| `OutputFormat.NPZ`  | `.npz`    | Accumulates in memory, compressed on close |

Every output file contains the same contents:

* **Datasets:** `outputs`, `coords`, `tissue_ratios`, `thumbnail`, `tissue_mask` — plus `input_gene_names` and `output_gene_names` for M-Optimus.
* **Metadata attributes:** `slide_name`, `tile_size`, `stride`, `mpp`, `slide_dimensions`, `slide_dimensions_at_mpp`, `num_tiles`.

See [Visualizing results](/guides/get-started/visualizing-results) to load and plot them.