Metadata-Version: 2.4
Name: mopet-moe
Version: 0.1.0
Summary: MoPET: parameter-efficient mixture-of-experts for unified medical image classification.
Author-email: Sebastian Doerrich <sebastian.doerrich@uni-bamberg.de>
License: MIT
Project-URL: Homepage, https://github.com/sdoerrich97/mopet
Project-URL: Weights, https://huggingface.co/sdoerrich97
Project-URL: Issues, https://github.com/sdoerrich97/mopet/issues
Keywords: medical-imaging,mixture-of-experts,parameter-efficient-fine-tuning,lora,vision-transformer,medmnist,pytorch,deep-learning
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch<2.10,>=2.9
Requires-Dist: timm<1.1,>=1.0.22
Requires-Dist: peft==0.18.0
Requires-Dist: numpy<3,>=2
Requires-Dist: huggingface-hub>=0.30
Requires-Dist: safetensors>=0.5
Requires-Dist: pillow>=10.0
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: experiments
Requires-Dist: accelerate>=1.0; extra == "experiments"
Requires-Dist: medmnist<4,>=3.0; extra == "experiments"
Requires-Dist: medmnistc>=0.1; extra == "experiments"
Requires-Dist: scikit-learn>=1.5; extra == "experiments"
Requires-Dist: wandb>=0.16; extra == "experiments"
Requires-Dist: pandas>=2.0; extra == "experiments"
Requires-Dist: tqdm>=4.65; extra == "experiments"
Requires-Dist: matplotlib>=3.8; extra == "experiments"
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file

# MoPET: Parameter-Efficient Mixture-of-Experts for Unified Medical Image Classification @ MICCAI 2026 EMA Workshop

<p align="center">
  [<a href="#">Preprint (coming soon)</a>]
  [<a href="https://pypi.org/project/mopet-moe/">PyPI</a>]
  [<a href="https://huggingface.co/collections/sdoerrich97/mopet-6a6b05867660d60582735c9c">Pretrained Weights (HF)</a>]
  [<a href="#citation">Citation</a>]
</p>

## Overview

MoPET is a mixture-of-experts method for parameter-efficient fine-tuning (PEFT) of
foundation models on 2D medical images. A learned sparse router directs each input
through a small, top-k subset of low-rank PEFT experts (LoRA and BOFT) injected into a
frozen DINOv3 backbone, sharing adapter capacity across datasets while limiting the
gradient conflict that arises when heterogeneous domains are trained jointly. On
MedMNIST+, this design lets a single model consolidate multiple classification tasks
that would otherwise each need their own fine-tuned network.

<p align="center">
  <img src="assets/method.png" width="90%" alt="MoPET method overview">
</p>
<p align="center"><i>Standard PEFT trains one adapted model per dataset (left). MoPET
routes each input through a shared feature router to a frozen pretrained backbone plus
a pool of specialized PEFT experts, consolidating all datasets into a single
multi-domain model (right).</i></p>

<p align="center">
  <img src="assets/architecture.png" width="90%" alt="MoPET architecture detail">
</p>
<p align="center"><i>(A) Interleaved batch sampling keeps every training batch
diverse across the pooled datasets. (B) Inside a MoPET layer, a router selects the
top-k PEFT experts per token; their outputs are combined with the frozen pretrained
projection. (C) A dataset router uses the pooled feature and the sample's dataset id to
dispatch it to the matching classification head.</i></p>

### Key Contributions
- Across 12 MedMNIST+ datasets, parameter-efficient fine-tuning of a frozen foundation
  backbone outperforms full end-to-end fine-tuning.
- MoPET, a mixture-of-experts built entirely from PEFT modules, unifies distinct
  classification tasks in a single model and beats isolated per-domain adapters on a
  four-dataset pool.
- A cross-domain "booster" dynamic where co-training with auxiliary datasets improves
  accuracy on data-constrained target datasets.

## Installation

From PyPI (the distribution is `mopet-moe`; it still imports as `mopet`):
```bash
pip install mopet-moe
```
From source (adds the reproduction/training stack):
```bash
git clone https://github.com/sdoerrich97/mopet.git && cd mopet
pip install -e ".[experiments]"
```

## Quick Start

```python
from mopet import create_model

model = create_model(weights="unified").eval()   # downloads the adapter weights from HF; frozen DINOv3 from timm
```

See `examples/` for runnable inference, minimal-API, and training-CLI notebooks.

## Model Zoo

Weights live in the [MoPET HuggingFace Collection](https://huggingface.co/collections/sdoerrich97/mopet-6a6b05867660d60582735c9c).
The **Identifier** column is exactly the string to pass as `create_model(weights=...)`.

| Identifier | Datasets (head order) | Backbone | HF Repo |
|---|---|---|---|
| `unified` | Blood, Breast, Derma, Path | DINOv3 ViT-B/16 | [mopet_dinov3_unified_blood_breast_derma_path](https://huggingface.co/sdoerrich97/mopet_dinov3_unified_blood_breast_derma_path) |
| `booster-retina` | Breast, Blood, Retina, Path, OrganA | DINOv3 ViT-B/16 | [mopet_dinov3_booster_retina_breast_blood_retina_path_organa](https://huggingface.co/sdoerrich97/mopet_dinov3_booster_retina_breast_blood_retina_path_organa) |
| `booster-derma` | Derma, Blood, OCT, OrganS | DINOv3 ViT-B/16 | [mopet_dinov3_booster_derma_derma_blood_oct_organs](https://huggingface.co/sdoerrich97/mopet_dinov3_booster_derma_derma_blood_oct_organs) |

Each release carries only the ~7M trainable parameters (PEFT experts, routers, and
per-dataset heads); the frozen DINOv3 backbone is reconstructed from `timm` at load
time.

## Project Structure
```
mopet/            # the installable package: MoPET model, MoE/PEFT experts, create_model factory
experiments/      # reproduction code: configs, data, metrics, reference baselines, entry scripts — not on PyPI
examples/         # runnable inference / usage / training notebooks
for_huggingface/  # staged config + model-card assets for the released HF checkpoints
tests/            # pytest suite
scripts/          # local + cluster (SLURM/Apptainer) job generators
```

## Citation

```bibtex
@inproceedings{doerrich2026mopet,
  title     = {{MoPET}: Parameter-Efficient Mixture-of-Experts for Unified Medical Image Classification},
  author    = {Doerrich, Sebastian and W{\"u}rtinger, Daniel and Di Salvo, Francesco and Rai, Shyam Nandan and Ledig, Christian},
  booktitle = {MICCAI 2026 Workshop on Efficient Medical AI (EMA)},
  year      = {2026},
}
```

## License

The `mopet` code is released under the [MIT License](LICENSE). The frozen DINOv3
backbone weights are downloaded separately via `timm`/HuggingFace under their own
upstream license; only the code in this repository and the trainable-parameter
checkpoints in the HuggingFace collection above are covered by the MIT license.

## Changelog

### v0.1.0
- Initial public release accompanying the MICCAI 2026 EMA Workshop paper.
