Metadata-Version: 2.4
Name: mopet-moe
Version: 0.1.2
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: Paper, https://arxiv.org/abs/2607.29462
Project-URL: Weights, https://huggingface.co/collections/sdoerrich97/mopet-6a6b05867660d60582735c9c
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<3,>=2.9
Requires-Dist: timm<2,>=1.0.22
Requires-Dist: peft<0.19,>=0.18
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 @ EMA4MICCAI 2026 Workshop

<p align="center">
  [<a href="https://arxiv.org/abs/2607.29462">Preprint</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]"
```

### Requirements & reproducibility
`pip install` uses **permissive version ranges** (Python >= 3.12, `torch>=2.9,<3`,
`timm>=1.0.22,<2`, ...) so MoPET installs cleanly next to other packages and with newer releases.
The one version-sensitive dependency is `peft` (bounded to `0.18.x`): MoPET calls peft internal
layer classes, so a wider range is not guaranteed to work. For **bit-for-bit reproduction** of the
paper's environment, use the hash-pinned `requirements.txt` / `uv.lock` (what the `Dockerfile`
installs) rather than the ranges above.

## 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=...)`; list the
available checkpoints and their head layout programmatically with `mopet.list_pretrained()`.

| 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
assets/        # figures used by the README and paper
Dockerfile     # reproducible environment (multi-stage; the canonical way to reproduce results)
```

## Citation
```bibtex
@article{doerrich2026mopet,
      title={MoPET: Parameter-Efficient Mixture-of-Experts for Unified Medical Image Classification}, 
      author={Sebastian Doerrich and Daniel W{\"u}rtinger and Francesco {Di Salvo} and Shyam Nandan Rai and Christian Ledig},
      year={2026},
      eprint={2607.29462},
      archivePrefix={arXiv},
      primaryClass={eess.IV},
      url={https://arxiv.org/abs/2607.29462}, 
}
```

## 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.1
- Relaxed dependency ranges for easier installation (`torch<3`, `timm<2`, `peft` bounded to 0.18.x);
  exact reproducible versions remain in `requirements.txt` / `uv.lock`.
- Added `mopet.list_pretrained()` to discover the released checkpoints.
- Expanded and executed the example notebooks (inference, API usage, training) with embedded outputs.
- Added `CITATION.cff`; slimmed the public repository to the code and Docker reproduction path.

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