Metadata-Version: 2.5
Name: cnn-classifier-toolkit
Version: 0.1.0
Summary: A config-driven, reproducible PyTorch toolkit for CNN image classification.
Project-URL: Homepage, https://github.com/pengzhao-ai/cnn-classifier
Project-URL: Documentation, https://pengzhao-ai.github.io/cnn-classifier/
Project-URL: Repository, https://github.com/pengzhao-ai/cnn-classifier
Project-URL: Changelog, https://github.com/pengzhao-ai/cnn-classifier/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/pengzhao-ai/cnn-classifier/issues
Author: Peng Zhao
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: classification,cnn,deep-learning,experiment-tracking,image-classification,pytorch,reproducible-research,toolkit
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.11
Requires-Dist: jinja2>=3.1
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=2.0
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tifffile>=2024.1
Requires-Dist: torch<3,>=2.15
Requires-Dist: torchvision<1,>=0.29
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: hypothesis>=6.98; extra == 'all'
Requires-Dist: mkdocs-material>=9.5; extra == 'all'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'all'
Requires-Dist: mypy>=1.11; extra == 'all'
Requires-Dist: pandas>=2.2; extra == 'all'
Requires-Dist: pre-commit>=3.7; extra == 'all'
Requires-Dist: pytest-cov>=5.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.6; extra == 'all'
Requires-Dist: scikit-learn>=1.4; extra == 'all'
Requires-Dist: tensorboard>=2.16; extra == 'all'
Requires-Dist: torchinfo>=1.8; extra == 'all'
Requires-Dist: types-pyyaml>=6.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.98; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pandas>=2.2; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: tracking
Requires-Dist: tensorboard>=2.16; extra == 'tracking'
Provides-Extra: viz
Requires-Dist: scikit-learn>=1.4; extra == 'viz'
Requires-Dist: torchinfo>=1.8; extra == 'viz'
Description-Content-Type: text/markdown

# CNN Classifier Toolkit

[![Python 3.11–3.13](https://img.shields.io/badge/python-3.11--3.13-blue)](https://www.python.org/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-pengzhao--ai.github.io%2Fcnn--classifier-indigo)](https://pengzhao-ai.github.io/cnn-classifier/)

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

| Experiment | Result | Budget |
|---|---:|---|
| CIFAR-10 scratch baseline | **92.25% test**, 92.78% best validation | 50 epochs, 22.3 min MPS |
| ResNet-18 fine-tune, 32×32 | **94.98% test** | 30 epochs, 19.5 min MPS |
| ResNet-18 scratch, 32×32 | 90.88% test | 30 epochs, 19.6 min MPS |
| ResNet-18 linear probe | 62.66% test | 30 epochs, 8.4 min MPS |
| Four core ablations | BN on +19.4 pp; cosine +8.5 pp; residual off +0.7 pp; augmentation off +3.1 pp | 8 epochs, 10k train subset |
| Optical degradation classifier | 85.71% test | 20 epochs, 7.5 s MPS |
| Bring-your-own-data quickstart | contract verified | 2 epochs, under a minute |

![CIFAR-10 training history](https://raw.githubusercontent.com/pengzhao-ai/cnn-classifier/main/docs/images/cifar10_training_history.png)

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](https://pengzhao-ai.github.io/cnn-classifier/case_studies/cifar10/)
for the environment and caveats.

## What is in the core

| Area | What you get |
|---|---|
| Data | torchvision, ImageFolder, CSV manifest, NumPy, and synthetic adapters; 8-bit and 16-bit image I/O; group-safe splits; leakage and duplicate inspection |
| Models | configurable simple CNN, configurable residual CNN, torchvision backbone wrapper, 32×32 stem adaptation, freezing, differential parameter groups |
| Training | callbacks, early stopping, checkpoint/resume, AMP, gradient clipping and accumulation, MixUp/CutMix, EMA, warmup/cosine/step/plateau schedules |
| Evaluation | top-k, per-class metrics, confusion matrices, NLL, calibration (ECE/MCE/Brier), bootstrap intervals, TTA, latency, error analysis |
| Diagnostics | one-batch overfit, shape tracing, gradient reports, determinism checks |
| Artifacts | resolved config, environment and git metadata, data fingerprints, metrics, checkpoints, predictions, figures, model contract |
| Reports | self-contained HTML and Markdown, inline figures, no CDN or network dependency |
| Devices | automatic CUDA, Apple MPS, or CPU selection |

## Install

### From PyPI

```bash
pip install cnn-classifier-toolkit
cnncls doctor
```

### From a checkout

```bash
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:

```bash
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:

```bash
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:

```bash
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

| Demo | What it shows | Entry point |
|---|---|---|
| CIFAR-10 scratch | reference residual CNN and the full training path | `python demos/cifar10/scripts/run_scratch.py` |
| Transfer benchmark | scratch vs linear probe vs fine-tune at 32×32 | `python demos/cifar10/scripts/run_transfer.py` |
| Ablations | four controlled pairs on a reduced CIFAR split | `python demos/ablations/run_ablations.py` |
| Optical degradation | manifest data, group-safe splits, confusion analysis | `python demos/optics_degradation/scripts/run_optics.py` |
| Bring your own data | raw-to-intake contract and custom adapters | `python demos/bring_your_own_data/scripts/run_quickstart.py` |

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

## Command line

| Command | Purpose |
|---|---|
| `cnncls init DIR` | Scaffold a config, README, and data layout |
| `cnncls doctor` | Versions, device selection, optional dependencies |
| `cnncls inspect-data -c CONFIG` | Class balance, duplicates, corruption, leakage, model contract |
| `cnncls debug -c CONFIG` | One-batch overfit, shape trace, gradients, determinism |
| `cnncls train -c CONFIG` | Train, evaluate, write figures and the report |
| `cnncls evaluate --checkpoint PATH` | Evaluate on `test` or `val`, write predictions and metrics |
| `cnncls predict --checkpoint PATH --input PATH` | Image, folder, or manifest inference |
| `cnncls report --run DIR` | Rebuild HTML and Markdown from artifacts |
| `cnncls compare RUN... --out DIR` | Fair comparison with test-fingerprint enforcement |

`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/](https://pengzhao-ai.github.io/cnn-classifier/):

- [Quickstart](https://pengzhao-ai.github.io/cnn-classifier/quickstart/)
- [How it works](https://pengzhao-ai.github.io/cnn-classifier/how_it_works/)
- [Models & architectures](https://pengzhao-ai.github.io/cnn-classifier/models/)
- [Configuration](https://pengzhao-ai.github.io/cnn-classifier/configuration/)
- [Techniques](https://pengzhao-ai.github.io/cnn-classifier/techniques/augmentation/)
- [CIFAR-10 demo](https://pengzhao-ai.github.io/cnn-classifier/case_studies/cifar10/)
- [Bring your own data](https://pengzhao-ai.github.io/cnn-classifier/bring_your_own_data/)
- [CLI](https://pengzhao-ai.github.io/cnn-classifier/cli/)
- [API](https://pengzhao-ai.github.io/cnn-classifier/api/)

## Project layout

```text
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

```bash
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`](CONTRIBUTING.md).

## License

Apache-2.0. See [`LICENSE`](LICENSE).

## Citation

If you use this toolkit, cite it using [`CITATION.cff`](CITATION.cff).
