CNN Classifier Toolkit

A config-driven, reproducible PyTorch toolkit for CNN image classification.

The toolkit turns a new image/label dataset into a trained, evaluated, and reported classifier through a typed YAML configuration. The same library powers the command line, so a quick smoke test and a full experiment use one pipeline.

It is published on PyPI as cnn-classifier-toolkit; the import package remains cnn_classifier and the CLI remains cnncls.

Results at a glance

Reference: 92.42% validation / 92.61% test on MPS, seed 42. The reproduced test result is within 0.4 percentage points and clears the ≥90% gate. See the CIFAR-10 case study for the environment and caveats.

What is in the core

Install

From PyPI

pip install cnn-classifier-toolkit
cnncls doctor

From a checkout

make sync
source .venv/bin/activate
cnncls doctor

make sync installs the package non-editable so the cnncls entry point works reliably on macOS, where an editable .pth can be hidden after PyTorch loads. Run make sync again after changing library code. Without activating the environment, use uv run --no-sync cnncls ....

Quickstart

Train a tiny deterministic smoke model with no downloads:

cnncls train -c configs/tests/synthetic.yaml --set training.epochs=1

The command creates a run directory under runs/ containing the resolved configuration, data fingerprints, model contract, checkpoints, test predictions, figures, report.html, and report.md.

Inspect the pipeline before training:

cnncls inspect-data -c configs/tests/synthetic.yaml
cnncls debug -c configs/tests/synthetic.yaml --overfit-batch --steps 20
cnncls train -c configs/tests/synthetic.yaml --dry-run

Evaluate, predict, and rebuild reports from artifacts:

cnncls evaluate --checkpoint runs/<run>/checkpoints/best.pt --split test
cnncls predict --checkpoint runs/<run>/checkpoints/best.pt --input image.png
cnncls report --run runs/<run>
cnncls compare runs/<run-a> runs/<run-b> --out results/comparison

Demos

The bring-your-own-data quickstart uses a committed 16-bit fixture and finishes in a few seconds.

Command line

train --dry-run builds the dataset and model, runs one forward/backward pass, prints the contract and parameter counts, and exits without writing a run.

Documentation

The full site is published at https://pengzhao-ai.github.io/cnn-classifier/:

• Quickstart
• How it works
• Models & architectures
• Configuration
• Techniques
• CIFAR-10 demo
• Bring your own data
• CLI
• API

Project layout

src/cnn_classifier/
├── config/       typed YAML schema, defaults chain, CLI overrides
├── core/         devices, seeding, hashing, shared contracts
├── data/         adapters, image I/O, splits, transforms, inspection
├── models/       CNN builders, torchvision wrapper, transfer utilities
├── training/     trainer, callbacks, checkpoints, optimizer, schedules, AMP
├── evaluation/   metrics, calibration, bootstrap, latency, comparison
├── diagnostics/  overfit, tracing, gradients, determinism
├── viz/          publication-style figures and HTML/Markdown reports
├── runs/         run directories and artifact writers
└── cli.py        `cnncls` command line

Development

make test        # library tests
make coverage    # core coverage gate
make lint        # ruff
make typecheck   # mypy
make docs        # this site
make build       # wheel and sdist
make gate        # all of the above

Contributor notes are in CONTRIBUTING.md.

License

Apache-2.0. See LICENSE.

Citation

If you use this toolkit, cite it using CITATION.cff.