ahcore

ahcore is the AI for Oncology core toolkit for computational-pathology pipelines: the reusable building blocks that sit between whole-slide images and a training run. It is a pure-Python library, meant to be composed inside a larger pipeline rather than run on its own.

This repository is automatically synced from the AI for Oncology monorepo.

What ahcore offers

ahcore is a toolkit of composable building blocks for whole-slide-image deep learning, not an end-to-end application. A consumer pipeline assembles these pieces and owns the experiment logic. It decides how data is split, whether to cross-validate, and how runs are orchestrated. ahcore provides the parts.

• A data catalog. A SQLAlchemy-backed manifest of patients, slides, masks, labels, and named splits, queried through a DataManager. ahcore stores and serves splits (e.g. fit/validate/test membership, or membership supplied in memory). How you draw them is up to you.
• Views and adapters. Lazy per-slide and per-tile accessors over the catalog, plus an adapter seam (view → AdapterBundle) that turns them into named, model-ready tensors. Ships adapters for foundation-model tile features, patient labels, bulk RNA expression, and image+mask pairs. Adapters are the main extension point.
• Feature extraction and caching. Run a packaged foundation-model encoder over a slide's tiles and persist the per-slide features to HDF5, keyed deterministically. This is a distinct precompute step: at training time the feature adapters read from that cache, they do not extract on the fly (doing so would be too slow for a realistic training run).
• Datamodules and models. PyTorch Lightning datamodules that assemble batches from adapters (single- or multi-modal), plus model heads: attention-based MIL (ABMIL), mean-pool MIL (MeanMIL), encoders, a concatenation fusion head, and segmentation wrappers.
• Task and training scaffolding. A Task protocol (choose inputs and targets, compute loss and metrics) and a thin MultiModalLightningModule that runs training/validation/test by delegating to the task. You supply the concrete tasks.
• Slide-sized raster I/O. Stream model outputs (segmentation masks, attention or probability maps) tile-by-tile into a chunked Zarr store, then read arbitrary regions back like a slide, to stitch, overlay, or export to a pyramidal TIFF.
• Transforms and augmentations. Tile transforms (including polygon-to-mask) and feature-space augmentations.

ahcore ships no end-to-end command-line application; it is a library.

Installation

pip install ahcore

Requires Python ≥ 3.11. The training stack (PyTorch Lightning) is a core dependency. ahcore is a training-scaffolding library, not an optional add-on.

Manifests that read slides with OpenSlide (reader OPENSLIDE) need dlup's OpenSlide backend:

pip install "ahcore[openslide]"

Development

ahcore is developed in the AI for Oncology monorepo and synced to this repository. To work on it here, standalone:

pip install -e ".[dev]"
pytest

Inside the monorepo it is built and tested with Bazel (bazelisk test //aifo/ahcore/tests/...).

License

Apache 2.0 — see LICENSE.