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

Generic WSI inference orchestrator.

Provides [`Inference`](/sdk-reference/inference/inference#inference), a high-level facade that wires together model construction, tissue segmentation, tile extraction, and per-tile prediction via a remote model endpoint.  The internal `_SlideInference` class handles single-WSI processing.

## Inference

```python theme={null}
class Inference(model_name: Models | str,
                api_url: str | None = None,
                *,
                cohort: Cohort | None = None,
                wsi_dir: str | Path | None = None,
                bulk_rna_dir: str | Path | None = None,
                mask_dir: str | Path | None = None,
                tissue: bool = True,
                mask_threshold: float = 0.5,
                output_path: str | Path = _DEFAULT_OUTPUT_PATH,
                output_format: OutputFormat | str = OutputFormat.ZARR,
                max_concurrency: int = 256,
                workers: int | None = None,
                experiment: str | None = None,
                run: int | None = None,
                variant: str | None = None,
                description: str | None = None,
                backend: str = 'remote',
                wsi_backend: str | None = None,
                coordinates: Sequence[tuple[int, int]] | None = None,
                **kwargs: Any)
```

High-level multi-WSI inference facade.

Wraps model construction, tissue segmentation, tile extraction, and per-tile prediction behind a simple API.  A single instance is reusable across many WSIs.

The `Cohort` is the single source of truth — all inputs, outputs, and processing status live there. The manifest is auto-saved after each WSI completes, enabling seamless resume on restart.

**model\_name**

Model identifier. Use [`Models`](/sdk-reference/models/types#models) enum values or a plain string matching a YAML config.

**api\_url**

Base URL for the HTTP backend. Required when *backend* is `"remote"`.

**cohort**

A pre-built [`Cohort`](/sdk-reference/data/cohort#cohort) manifest.  If not provided, one is created on first use (ad-hoc mode).

**wsi\_dir**

Directory containing WSI files.

**bulk\_rna\_dir**

Directory containing bulk RNA files.

**mask\_dir**

Directory containing pre-computed tissue masks.

**tissue**

Whether to auto-compute tissue masks via the `tissue-seg` model. Defaults to `True`.

**mask\_threshold**

Minimum tissue fraction to keep a tile.

**output\_path**

Root directory for the structured workspace.

**output\_format**

On-disk format for predictions/embeddings.

**max\_concurrency**

Maximum concurrent HTTP requests.

**workers**

Number of WSIs to process in parallel. When `None` (the default), it falls back to `max(1, gpu_count)` from the local CUDA device count. This is meaningful for the `local` backend; for the `remote` and `aws` backends the GPUs live server-side, so a warning is logged and this should be set explicitly.

**experiment**

Experiment / study name for directory nesting.

**run**

Run number for repeated experiments.

**variant**

Sub-variant label (e.g. stain method, threshold).

**description**

Free-text note saved in the config.

**backend**

`"remote"` (HTTP) or `"aws"` (SageMaker).

**coordinates**

Optional explicit tile positions as `(x, y)` top-left, slide-origin pixel pairs at the model tile-spec resolution. When supplied, tiles are extracted at exactly these locations (one per coordinate) and tissue masking is bypassed, for every slide this instance processes. Intended for predicting at predefined locations (e.g. PseudoVisium / hex-pooled / Visium spots) and benchmarking against spatial-transcriptomics ground truth. Spot tables report spot *centres*; convert to top-left first (subtract half the spot size in x and y). Coordinate mode targets a single WSI at a time.

\*\***kwargs**

Backend-specific arguments forwarded to `Backbone`.

**Example**:

```python theme={null}
from bioptimus.models import Models
from bioptimus.inference import Inference
from bioptimus.data.cohort import Cohort

cohort = Cohort.from_directories("/data/wsis", "/data/rna")

infer = Inference(
    model_name=Models.H1,
    api_url="http://localhost:8000",
    cohort=cohort,
    experiment="brca-cohort-a",
    run=1,
)
infer.run()  # processes all pending WSIs
```

***

#### from\_workspace

```python theme={null}
@classmethod
@log_failures
def from_workspace(cls, workspace: str | Path, **overrides: Any) -> Inference
```

Resumes an [`Inference`](/sdk-reference/inference/inference#inference) from a saved workspace.

Loads both the config YAML and the cohort manifest, allowing seamless resume of an interrupted run.

**workspace**

Path to the workspace directory.

\*\***overrides**

Keyword overrides applied on top of the config values.

**Returns**:

A fully-initialised [`Inference`](/sdk-reference/inference/inference#inference) with cohort state.

***

#### save\_config

```python theme={null}
@log_failures
def save_config(path: str | Path | None = None) -> Path
```

Persists the current configuration as a YAML file.

**path**

Destination file path. Defaults to the workspace.

**Returns**:

Path to the written config file.

***

#### cohort

```python theme={null}
@property
def cohort() -> Cohort
```

The cohort manifest (single source of truth).

***

#### wsi\_dir

```python theme={null}
@property
def wsi_dir() -> Path | None
```

Directory containing WSI files, or `None` if not set.

***

#### model\_name

```python theme={null}
@property
def model_name() -> str
```

Name of the model this instance targets.

***

#### workspace

```python theme={null}
@property
def workspace() -> Path
```

Resolved experiment workspace root directory.

***

#### manifest\_path

```python theme={null}
@property
def manifest_path() -> Path
```

Path to the cohort manifest YAML in the workspace.

***

#### find

```python theme={null}
@log_failures
def find(wsi_dir: str | Path | None = None,
         bulk_rna_dir: str | Path | None = None,
         mask_dir: str | Path | None = None,
         *,
         patient_id_fn: Callable[[str], str] | None = None) -> Cohort
```

Discovers WSI, bulk RNA, and mask files; builds the cohort.

Scans directories for supported files, auto-pairs them, and stores the result as the instance cohort.

**wsi\_dir**

Directory to scan for WSI files.

**bulk\_rna\_dir**

Directory for bulk RNA files.

**mask\_dir**

Directory for pre-computed masks.

**patient\_id\_fn**

Optional callable that maps a filename stem to a patient ID.

**Returns**:

The constructed [`Cohort`](/sdk-reference/data/cohort#cohort).

**Raises**:

* `ValueError` - If no WSI directory is available.

***

#### run

```python theme={null}
def run(mode: InferenceMode | str = InferenceMode.EMBEDDING,
        *,
        force: bool = False) -> list[Path | None]
```

Processes all pending WSIs in the cohort.

Automatically resumes — WSIs whose output already exists on disk are skipped unless *force* is `True`.

**mode**

The `InferenceMode` to run (`EMBEDDING` or `PREDICTION`); a mode string is also accepted.

**force**

Reprocess all WSIs regardless of status.

**Returns**:

List of output paths, one per WSI in cohort order.

**Raises**:

* `BioptimusValueError` - If this instance has `coordinates` set (the full-cohort form is incompatible with the single-WSI contract).

***

#### predict

```python theme={null}
@log_failures
def predict(wsi_path: str | Path | list[str | Path] | None = None,
            *,
            bulk_rna_path: str | Path | None = None,
            force: bool = False) -> Path | None | list[Path | None]
```

Runs prediction for one or more WSIs.

When called without arguments, processes the full cohort. Single paths are auto-registered in the cohort.

When this instance was constructed with `coordinates=`, tiles are extracted at those fixed locations for the single processed WSI.

**wsi\_path**

Single WSI path, list of paths, or `None` to process the full cohort.

**bulk\_rna\_path**

Optional bulk RNA CSV override.

**force**

Reprocess even if already done.

**Returns**:

The output path for a single WSI (raising on failure), or a list of
output paths for a list input or the full cohort, with `None` in
the slots of slides that failed (logged, recorded in the manifest,
and skipped so the batch completes).

**Raises**:

* `BioptimusValueError` - If this instance has `coordinates` set and a list input or the full-cohort form is requested.

***

#### embed

```python theme={null}
@log_failures
def embed(wsi_path: str | Path | list[str | Path] | None = None,
          *,
          bulk_rna_path: str | Path | None = None,
          force: bool = False) -> Path | None | list[Path | None]
```

Runs embedding extraction for one or more WSIs.

When called without arguments, processes the full cohort. Single paths are auto-registered in the cohort.

**wsi\_path**

Single WSI path, list of paths, or `None` to process the full cohort.

**bulk\_rna\_path**

Optional bulk RNA CSV override.

**force**

Reprocess even if already done.

**Returns**:

The output path for a single WSI (raising on failure), or a list of
output paths for a list input or the full cohort, with `None` in
the slots of slides that failed (logged, recorded in the manifest,
and skipped so the batch completes).

**Raises**:

* `BioptimusValueError` - If this instance has `coordinates` set and a list input or the full-cohort form is requested.

***

#### tissue

```python theme={null}
@log_failures
def tissue(wsi_path: str | Path | list[str | Path] | None = None,
           *,
           force: bool = False) -> np.ndarray | None | list[np.ndarray | None]
```

Computes (or loads cached) tissue masks.

When called without arguments, processes all WSIs in the cohort that don't yet have masks.

**wsi\_path**

Single path, list, or `None` for full cohort.

**force**

Recompute even if a cached mask exists.

**Returns**:

The mask for a single path (raising on failure), or a list of masks
for the full cohort or a list input, with `None` in the slots of
slides whose mask computation failed (logged and skipped).

***

#### status

```python theme={null}
def status() -> str
```

Returns and prints a processing status summary.

**Returns**:

A human-readable summary of cohort processing progress.

***

#### failures

```python theme={null}
@property
def failures() -> list[tuple[str, str, str]]
```

Returns WSIs with errors as (wsi\_id, model, error).

***

#### report

```python theme={null}
def report() -> str
```

Prints and returns a failure summary.

**Returns**:

A formatted string listing all failed WSIs, or a success message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.