Metadata-Version: 2.5
Name: ahcore
Version: 0.1.0
Summary: Core building blocks for whole-slide-image deep learning pipelines
Project-URL: Homepage, https://github.com/NKI-AI/ahcore
Project-URL: Repository, https://github.com/NKI-AI/ahcore
Project-URL: Issues, https://github.com/NKI-AI/ahcore/issues
Author-email: Jonas Teuwen <j.teuwen@nki.nl>, Joren Brunekreef <j.brunekreef@nki.nl>
Maintainer-email: AI for Oncology <j.teuwen@nki.nl>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.11
Requires-Dist: dlup>=0.9.4
Requires-Dist: filelock>=3.12
Requires-Dist: h5py>=3.12
Requires-Dist: imageio>=2.37
Requires-Dist: kornia>=0.8
Requires-Dist: lightning>=2.6
Requires-Dist: numcodecs>=0.13
Requires-Dist: numpy>=2.0
Requires-Dist: omegaconf>=2.3
Requires-Dist: pandas>=2.0
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.10
Requires-Dist: rich>=13
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: torch>=2.6
Requires-Dist: tqdm>=4.66
Requires-Dist: typing-extensions>=4.10
Requires-Dist: zarr>=3.0
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: logging
Requires-Dist: mlflow>=3.4; extra == 'logging'
Requires-Dist: tensorboard>=2.19; extra == 'logging'
Provides-Extra: tracing
Requires-Dist: huggingface-hub; extra == 'tracing'
Requires-Dist: pyyaml; extra == 'tracing'
Requires-Dist: timm; extra == 'tracing'
Requires-Dist: transformers; extra == 'tracing'
Description-Content-Type: text/markdown

# 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

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

## Development

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

```bash
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](LICENSE).
