CIFAR10-style image loader tutorial (NPY, offline)

This tutorial mirrors a classic PyTorch recipe:

1. Load a labeled image dataset from disk (.npy exported from NumPy/PyTorch).
2. Split into train/test.
3. Build a small CNN by explicitly stacking layers.
4. Train for multiple epochs over shuffled minibatches through the public Trainer API.

To keep this runnable without network downloads, generate a small deterministic "CIFAR10-shaped" dataset locally:

• NN/Examples/Data/small_cifar10like_X.npy: shape (200, 3, 32, 32), dtype float32
• NN/Examples/Data/small_cifar10like_y.npy: shape (200,), dtype float32 labels 0..9

Generate it with:

python3 NN/Examples/Data/generate_small_data.py

Build:

• lake build NN.Examples.Data.Loaders.Cifar10Images

For command-line CIFAR training, use torchlean cnn or torchlean vit with --x, --y, and --n-total.

Optional flags (tutorial-specific):

• --data-dir PATH (default: NN/Examples/Data)
• --real-cifar10 (use data/real/cifar10/cifar10_train_*.npy, as prepared by scripts/datasets/download_example_data.py --cifar10)
• --x PATH, --y PATH (override the .npy files)
• --n-total N (number of rows in the selected .npy files; default 200)
• --seed S (controls split + shuffling + model initialization)
• --batch N
• --epochs E
• --lr LR (default: 0.001)
• --train-size N (default: 160)
• --check-only (validate paths, tensor shapes, and dataset splitting without training)

Why this tutorial matters:

• it shows the public Data file-loading path rather than only in-memory tensors;
• it keeps the model architecture familiar (Conv/ReLU/Pool stack + classifier head);
• it shows the "offline artifact" workflow many PyTorch users already have, where arrays have been pre-exported to .npy and training happens without any dataset download step.
• it stays on the same public Trainer surface as the model examples instead of dropping to the callback runner API.
• it shows that the trained result is still usable for immediate inference, not only for a terminal loss summary.

@[reducible, inline]

abbrev NN.Examples.Data.Loaders.Cifar10Images.classes : ℕ

@[reducible, inline]

abbrev NN.Examples.Data.Loaders.Cifar10Images.channels : ℕ

@[reducible, inline]

abbrev NN.Examples.Data.Loaders.Cifar10Images.height : ℕ

@[reducible, inline]

abbrev NN.Examples.Data.Loaders.Cifar10Images.width : ℕ

@[reducible, inline]

abbrev NN.Examples.Data.Loaders.Cifar10Images.nTotal : ℕ

def NN.Examples.Data.Loaders.Cifar10Images.mkModel {batch : ℕ} : TorchLean.nn.M (TorchLean.nn.Sequential (TorchLean.Shape.images batch channels height width) (Tensor.shapeOfDims [batch, classes]))

Small CNN (no BatchNorm): Conv -> ReLU -> Pool -> Conv -> ReLU -> Pool -> Linear(10).

def NN.Examples.Data.Loaders.Cifar10Images.source (xPath yPath : System.FilePath) (nRows : ℕ) : API.Data.LabeledSource

Shared offline CIFAR10-like tensor source used by this tutorial.

def NN.Examples.Data.Loaders.Cifar10Images.trainDataset (xPath yPath : System.FilePath) (nRows trainSize seed : ℕ) : TorchLean.Trainer.Dataset (TorchLean.Shape.image channels height width) (TorchLean.Shape.vec classes)

def NN.Examples.Data.Loaders.Cifar10Images.testDataset (xPath yPath : System.FilePath) (nRows trainSize seed : ℕ) : TorchLean.Trainer.Dataset (TorchLean.Shape.image channels height width) (TorchLean.Shape.vec classes)

Runtime-polymorphic test split used for --check-only reporting.

def NN.Examples.Data.Loaders.Cifar10Images.usage : String

Command-line help for the CIFAR10-style NPY loader tutorial.

def NN.Examples.Data.Loaders.Cifar10Images.main (args : List String) : IO Unit