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

<ParamField body="model_name">
  Model identifier. Use [`Models`](/sdk-reference/models/types#models) enum values or a plain string matching a YAML config.
</ParamField>

<ParamField body="api_url">
  Base URL for the HTTP backend. Required when *backend* is `"remote"`.
</ParamField>

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

<ParamField body="wsi_dir">
  Directory containing WSI files.
</ParamField>

<ParamField body="bulk_rna_dir">
  Directory containing bulk RNA files.
</ParamField>

<ParamField body="mask_dir">
  Directory containing pre-computed tissue masks.
</ParamField>

<ParamField body="tissue">
  Whether to auto-compute tissue masks via the `tissue-seg` model. Defaults to `True`.
</ParamField>

<ParamField body="mask_threshold">
  Minimum tissue fraction to keep a tile.
</ParamField>

<ParamField body="output_path">
  Root directory for the structured workspace.
</ParamField>

<ParamField body="output_format">
  On-disk format for predictions/embeddings.
</ParamField>

<ParamField body="max_concurrency">
  Maximum concurrent HTTP requests.
</ParamField>

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

<ParamField body="experiment">
  Experiment / study name for directory nesting.
</ParamField>

<ParamField body="run">
  Run number for repeated experiments.
</ParamField>

<ParamField body="variant">
  Sub-variant label (e.g. stain method, threshold).
</ParamField>

<ParamField body="description">
  Free-text note saved in the config.
</ParamField>

<ParamField body="backend">
  `"remote"` (HTTP) or `"aws"` (SageMaker).
</ParamField>

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

<ParamField body="**kwargs">
  Backend-specific arguments forwarded to `Backbone`.
</ParamField>

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

<ParamField body="workspace">
  Path to the workspace directory.
</ParamField>

<ParamField body="**overrides">
  Keyword overrides applied on top of the config values.
</ParamField>

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

<ParamField body="path">
  Destination file path. Defaults to the workspace.
</ParamField>

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

<ParamField body="wsi_dir">
  Directory to scan for WSI files.
</ParamField>

<ParamField body="bulk_rna_dir">
  Directory for bulk RNA files.
</ParamField>

<ParamField body="mask_dir">
  Directory for pre-computed masks.
</ParamField>

<ParamField body="patient_id_fn">
  Optional callable that maps a filename stem to a patient ID.
</ParamField>

**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`.

<ParamField body="mode">
  The `InferenceMode` to run (`EMBEDDING` or `PREDICTION`); a mode string is also accepted.
</ParamField>

<ParamField body="force">
  Reprocess all WSIs regardless of status.
</ParamField>

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

<ParamField body="wsi_path">
  Single WSI path, list of paths, or `None` to process the full cohort.
</ParamField>

<ParamField body="bulk_rna_path">
  Optional bulk RNA CSV override.
</ParamField>

<ParamField body="force">
  Reprocess even if already done.
</ParamField>

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

<ParamField body="wsi_path">
  Single WSI path, list of paths, or `None` to process the full cohort.
</ParamField>

<ParamField body="bulk_rna_path">
  Optional bulk RNA CSV override.
</ParamField>

<ParamField body="force">
  Reprocess even if already done.
</ParamField>

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

<ParamField body="wsi_path">
  Single path, list, or `None` for full cohort.
</ParamField>

<ParamField body="force">
  Recompute even if a cached mask exists.
</ParamField>

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