Image Classification

A free/open-source, configuration-driven pipeline for training, evaluating, and running image classifiers on arbitrary folder datasets.

The project deliberately has no built-in subject matter. A class is simply a directory of images; all domain assumptions—especially augmentation—remain visible in configuration rather than being hidden in code.

What it provides

• Transfer learning or training from scratch with ResNet, DenseNet, EfficientNet, MobileNet, and ViT.
• Deterministic, per-class train/validation/test splitting.
• CPU, CUDA, and Apple MPS device selection.
• AdamW or SGD, optional class weighting, label smoothing, cosine scheduling, mixed precision, and early stopping.
• Best/last state-dictionary checkpoints instead of serialized model objects.
• Accuracy, macro F1, per-class metrics, confusion matrices, and training-history artifacts.
• A resolved configuration, dataset manifest, environment metadata, and structural dataset fingerprint for each run.
• CLI, package layout, tests, continuous integration, Docker, and contributor/security guidance.

Dataset layout

Place images under one directory per class. Nested directories inside each class are supported. Class names are discovered from directory names and sorted consistently.

data/example/
├── class-a/
│   ├── image-001.jpg
│   └── image-002.jpg
├── class-b/
│   ├── image-001.png
│   └── image-002.png
└── class-c/
    └── nested/image-001.webp

Each class needs at least three images so that every split contains that class. Real training needs far more; the minimum exists only to make the split contract explicit.

Installation

Python 3.11 or newer is required.

python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'

PyTorch installation varies by operating system and accelerator. For CUDA-specific wheels, install PyTorch using the official selector first, then install this project.

First run

Generate a tiny synthetic dataset that checks the pipeline without implying a benchmark:

python examples/make_demo_dataset.py
image-classifier inspect --config configs/default.yaml
image-classifier train --config configs/default.yaml

The configured run directory will contain:

runs/example/
├── best.pt
├── last.pt
├── config-resolved.yaml
├── dataset-manifest.json
├── environment.json
├── history.csv
├── history-*.png
├── metrics.json
├── test-classification-report.json
├── test-confusion-matrix.csv
├── test-confusion-matrix.png
└── RUN.md

Commands

# List architectures
image-classifier models

# Inspect classes, counts, split sizes, and fingerprint
image-classifier inspect --config configs/default.yaml

# Train
image-classifier train --config configs/default.yaml

# Replace an existing run directory intentionally
image-classifier train --config configs/default.yaml --overwrite

# Re-evaluate a checkpoint against its saved split manifest
image-classifier evaluate --checkpoint runs/example/best.pt --split test

# Classify one image
image-classifier predict \
  --checkpoint runs/example/best.pt \
  --image path/to/image.jpg \
  --top-k 3

Configuration principles

The default configuration is conservative. Horizontal flipping, colour jitter, and rotation are disabled because they are not label-preserving in every domain. Enable only transformations that make sense for the dataset.

deterministic: true asks PyTorch to prefer deterministic algorithms. This can reduce performance and does not guarantee identical results across every hardware and software combination. The saved configuration, package versions, split manifest, and seed make a run auditable even when exact bitwise reproduction is impossible.

Model and data responsibility

This software does not validate whether a dataset is lawful, representative, or suitable for a particular decision. Users are responsible for licences, consent, privacy, class definitions, imbalance, distribution shift, and harmful use. Accuracy alone is not evidence that a classifier is safe or appropriate.

Do not treat the synthetic example as a performance benchmark.

Project status

0.1.0 is an alpha release. The training and reporting contracts are intentionally small and inspectable; backwards compatibility is not yet guaranteed.

Licence and provenance

MIT licensed. See LICENSE and AUTHORS.md. The repository is a 2026 domain-neutral redesign of an earlier experimental pipeline; no original domain-specific dataset, image, label, or branding is included.