Doraemon: a PyTorch library that keeps classification, retrieval and face recognition in one training engine

Three tasks, one engine, and the cost of that choice

Most teams that need image classification and image retrieval end up maintaining two codebases. A classifier is trained with cross-entropy on a label space. A retrieval model is trained with a metric-learning objective on an embedding space, then indexed and searched. The data loaders look similar, the augmentation policies overlap, and the evaluation code diverges anyway. Doraemon's answer is a single training engine at doraemon/engine/vision_engine.py that the README describes as a unified training flow for classification and embedding-based recognition tasks. The same repository also carries the optimization algorithms in doraemon/engine/optimizer.py, which the README lists as covering SGD, Adam, SAM and layer-specific learning rates, plus the losses that only make sense for embeddings: ArcFace, CircleLoss and MagFace among them. The audience is an engineer who already knows PyTorch and timm and does not want to reimplement margin-based softmax heads or a GradCAM wrapper before running a first experiment. The trade-off is real: a unified engine has to serve two objectives that want different defaults, and the repository's own task table shows the strain, with face recognition still listed as in progress.

The timm backbone is the model, everything else is a head

The architecture is not a novel network. The README states that Doraemon supports 1000+ visual backbones through timm, and that this covers everything returned by timm.list_models(pretrained=True), naming CLIP, SigLIP, DeiT, BEiT, MAE, EVA, DINO, ResNet, Swin Transformer and ViT as examples. So the data flow is: pick a timm backbone, attach a head from the library's metric-learning set, feed it through the transforms in doraemon/dataset/transforms.py, and let the vision engine drive the loop. That transform module is where the library earns some of its keep, listing CutOut, ColorJitter, Copy-Paste, Mixup and class-specific augmentation. Class-specific augmentation is the interesting entry, because it implies per-class policies rather than one global recipe, which matters when a dataset is long-tailed. For interpretation, doraemon/utils/cam.py provides GradCAM-based model interpretation and what the README calls bad-case analysis. Nothing here is exotic. The value is that these pieces are already wired to each other, so swapping a ResNet for a Swin does not require rewriting the training script.

Getting a first run: pip, venv, and two dataset entry points

The README gives a concrete install path. Create and activate a virtual environment, then install the published package:

python -m venv doraemon source doraemon/bin/activate pip install doraemon-torch

Note the name mismatch: the repository is Doraemon, the importable package is doraemon, and the PyPI distribution is doraemon-torch. For development the README offers pip install -e . from a clone. The README badges pin the environment at Python 3.10, PyTorch 2.5.1 or later, torchmetrics 0.11.4, timm 0.9.16 and OpenCV 4.7.0. Treat those as the tested combination rather than a hard requirement, since the README does not state what happens outside it. For data, the README points at three Hugging Face dataset entry points: Oxford-IIIT Pet for classification, an Ecommerce Product dataset for retrieval, and MS-Celeb-1M-v1c for face recognition. The classification and retrieval docs are linked from the task table, at doraemon/models/classifier/README.md and doraemon/models/representation/README_CBIR.md respectively. Those two files are where the actual config keys and training commands live; the top-level README does not reproduce them, so you will be reading them in the repository rather than here.

Face recognition is the weakest link, and the README says so

The task status table is unusually honest. Image classification and content-based image retrieval are both marked Supported. Face recognition is marked In progress, with the note that training on MS-Celeb-1M-v1c and evaluation on LFW are supported internally but the end-to-end public pipeline is still being organized. The tutorials section repeats this: classification and retrieval have docs, and the face recognition entry reads Stay tuned. If your project needs face recognition, that is a stop sign. The losses are present (ArcFace, MagFace, CircleLoss), the training data is named, and the validation set is named, but the path from a fresh clone to a working face model is not documented. You would be reconstructing the pipeline from the engine and optimizer source. That is possible for someone comfortable reading the training loop, and unreasonable for anyone who picked the library to avoid exactly that work. The second limitation is narrower but worth flagging: the README's own highlights list places Label smoothing, OHEM, Focal Loss, ArcFace, CircleLoss and MagFace under a heading that points at doraemon/engine/optimizer.py, which is an odd home for loss functions. It may be accurate, or it may be a stale link. Verify against the tree before you plan around it.

Deployment: a .pt file, a config, and Hugging Face AutoModel

Doraemon's deployment story has two modes, described in deploy/README.md. The first is local inference: run a trained .pt weight file together with the model configuration and inference code. The second is Hugging Face integration, publishing a model that loads through AutoModel.from_pretrained() and AutoProcessor.from_pretrained(). That second mode is the more consequential one, because it means a model trained here can be consumed by the standard transformers loading path instead of a bespoke loader. The README does not show the exact class names or the config schema that make AutoModel resolution work, so the deployment guide is the document to read before you commit to this route. One thing the README does not address at all is the licence interaction between the library and the weights you produce. The repository is GPL-3.0, while the README's badge row displays an MIT badge pointing at the LICENSE file. Those two signals conflict. If you plan to redistribute a model or ship it inside a product, resolve that discrepancy from the actual LICENSE file rather than the badge, and get your own advice on what GPL-3.0 means for your distribution model.

Where a plain timm script or a dedicated face library fits better

The honest alternative for classification alone is a short script on top of timm plus torchmetrics. timm already supplies the backbones and pretrained weights, and torchmetrics already supplies accuracy, precision and recall. If your task is single-label classification with a balanced dataset, Doraemon's unified engine buys you little, and you take on a GPL-3.0 dependency and a library whose versioning is still early (the README badge shows 0.0.10a while the releases list shows v0.1.0, another discrepancy to check). The alternative for face recognition is a library built around that task specifically, where the alignment step, the margin schedule and the verification protocol are the documented core rather than a work-in-progress entry in a status table. Doraemon's differentiator is the middle ground: retrieval and classification sharing one engine, one optimizer module and one transform stack, with metric-learning heads already available. If you need both tasks and want one place to maintain them, that is the case for this repository. If you need one of the three tasks and nothing else, the narrower tool is the better fit.

Maintenance surface: what you inherit when you pin this

Doraemon is not archived and the last push recorded is 2026-05-05, with a paper at arXiv:2511.04394 dated 2025.11.07 and a v0.1.0 release in March 2025. The version signals do not line up: the README badge reads doraemon-0.0.10a, the releases list shows v0.1.0, and the badge row carries an MIT licence marker against a GPL-3.0 repository. Each of those is a small thing on its own and a reason to read the source before pinning on all three together. The upgrade cost you inherit is mostly the timm coupling. Because backbones come from timm.list_models, a timm major version can change what is available and how pretrained weights are named, and the README pins timm 0.9.16. If you upgrade timm independently of Doraemon, you are outside the combination the badges describe. The same applies to torchmetrics 0.11.4 and PyTorch 2.5.1 or later. Practically, that means freezing the environment, or testing an upgrade against the classification and CBIR docs before rolling it out. There is no stated deprecation policy and no migration guide in the material, so treat each release as something to read rather than something to absorb automatically.

Editorial conclusion

Adopt Doraemon if you already train timm backbones and want classification and embedding-based retrieval to share one engine, one optimizer module and one transform stack, and if the GPL-3.0 licence fits how you ship. Do not adopt it for a production face recognition system today: the README lists that task as in progress and says the public end-to-end pipeline is still being organized. Before committing, verify three things yourself: that pip install doraemon-torch resolves to the same version as the repository you reviewed, that the classification and CBIR tutorial docs still match the code paths they reference, and that the deployment guide's AutoModel and AutoProcessor flow works with a checkpoint you trained rather than a published one.

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. wuji3/Doraemon on GitHub