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

Run this tutorial with lake exe torchlean data_cifar10 --check-only to validate the files, or omit --check-only to train and print a prediction for a blank image. The held-out split is reported here; this tutorial does not compute test accuracy.

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 leading rows to load; default 200)
• --seed S (controls split + shuffling + model initialization)
• --batch N
• --epochs E
• --lr LR (default: 0.001)
• --train-size N (default: up to 160 rows, or up to 16 with --check-only)
• --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.

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

Command name used in diagnostics and by the top-level example runner.

def NN.Examples.Data.Loaders.Cifar10Images.classCount : ℕ

CIFAR-10 has ten classes.

def NN.Examples.Data.Loaders.Cifar10Images.inputChannels : ℕ

RGB input.

def NN.Examples.Data.Loaders.Cifar10Images.imageHeight : ℕ

CIFAR-10 images are 32 by 32.

def NN.Examples.Data.Loaders.Cifar10Images.imageWidth : ℕ

Width, matching imageHeight.

def NN.Examples.Data.Loaders.Cifar10Images.defaultRowCount : ℕ

Default number of leading images loaded from pre-generated or downloaded files.

def NN.Examples.Data.Loaders.Cifar10Images.model {batchSize : ℕ} : TorchLean.nn.Builder (TorchLean.nn.Sequential [batchSize, inputChannels, imageHeight, imageWidth] [batchSize, classCount])

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

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

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

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

Entry point. --check-only loads and validates the data and split without training. --real-cifar10 selects prepared real-data paths; neither mode generates missing files. Both switches are stripped before the remaining flags reach the shared training-flag parser.