README.md

---
license: mit
library_name: onnx
pipeline_tag: image-classification
tags:
- image-classification
- mnist
- gru
- onnx
- onnxruntime
- pytorch
- dlab
datasets:
- mnist
metrics:
- accuracy
---

# MNIST GRU Classifier

This repository contains a validation-selected MNIST GRU digit classifier trained with [dlab](https://github.com/tsilva/dlab).

## Architecture

![MNIST GRU architecture](assets/architecture.png)

## Results

3-seed confirmation and test audit for the selected GRU recipe:

| metric | value |
|---|---:|
| validation accuracy | 99.3667% ± 0.0816 pp |
| validation loss | 0.02311 ± 0.00367 |
| test accuracy | 99.2700% ± 0.0748 pp |
| test loss | 0.02425 ± 0.00234 |

Representative checkpoint selected by validation accuracy:

| metric | value |
|---|---:|
| seed | `9001` |
| selected validation accuracy | 99.4667% |
| selected validation loss | 0.01894 |
| test accuracy | 99.1700% |
| test loss | 0.02754 |

The ONNX model was exported from the validation-selected checkpoint. Test metrics were produced after the recipe was selected and were logged in W&B test-audit run [`enmuxlt3`](https://wandb.ai/tsilva/dlab/runs/enmuxlt3).

## Model Details

- Dataset: MNIST
- Architecture: GRU sequence classifier
- Sequence axis: `columns`
- Pooling: `last`
- Hidden width: `384`
- Recurrent layers: `1`
- Bidirectional: `false`
- Dropout: `0.2`
- Optimizer: AdamW
- Learning rate: `0.003`
- Weight decay: `0.001`
- Scheduler: cosine
- Label smoothing: `0`
- Batch size: `512`
- Training augmentation: `true`
- Checkpoint selection: max validation accuracy
- Source W&B run: [`fs4fa4vl`](https://wandb.ai/tsilva/dlab/runs/fs4fa4vl)

## Input / Output

Use `model.onnx` for code-independent inference.

- Input name: `images`
- Input shape: `[batch, 1, 28, 28]`
- Input dtype: `float32`
- Output name: `logits`
- Output shape: `[batch, 10]`

Preprocessing:

- Convert image to grayscale.
- Resize to `28 x 28`.
- Scale pixel values to `[0, 1]`.
- Normalize with mean `0.1307` and standard deviation `0.3081`.
- Arrange the tensor as channels-first `[batch, 1, 28, 28]`.

## Usage

Install the runtime dependencies:

```bash
pip install huggingface_hub onnxruntime pillow numpy
```

Run inference with the ONNX model:

```python
import numpy as np
import onnxruntime as ort
from huggingface_hub import hf_hub_download
from PIL import Image

LABELS = {
    0: "0",
    1: "1",
    2: "2",
    3: "3",
    4: "4",
    5: "5",
    6: "6",
    7: "7",
    8: "8",
    9: "9",
}

model_path = hf_hub_download(
    repo_id="tsilva/mnist-classifier-gru",
    filename="model.onnx",
)

image = Image.open("example.png").convert("L").resize((28, 28))
x = np.asarray(image, dtype=np.float32) / 255.0
x = (x - 0.1307) / 0.3081
x = x[None, None, :, :].astype(np.float32)

session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
logits = session.run(["logits"], {"images": x})[0]
prediction = int(logits.argmax(axis=1)[0])

print(prediction, LABELS[prediction])
```

## Labels

MNIST labels:

| id | label |
|---:|---|
| 0 | 0 |
| 1 | 1 |
| 2 | 2 |
| 3 | 3 |
| 4 | 4 |
| 5 | 5 |
| 6 | 6 |
| 7 | 7 |
| 8 | 8 |
| 9 | 9 |

## Files

- `model.onnx`: ONNX export of the validation-selected checkpoint. Prefer this file for portable inference.
- `model.ckpt`: PyTorch Lightning checkpoint for the same model. This is code-dependent and mainly useful for PyTorch-based inspection or continued experimentation.
- `config.yaml`: resolved Hydra training config.
- `metrics.csv`: training metrics from the uploaded checkpoint run.
- `metadata.json`: compact metadata for inference and provenance.

## Limitations

This GRU model treats each MNIST image as a short sequence rather than using convolutional inductive bias. It is intended for normalized `28 x 28` grayscale MNIST-style images; remaining errors are expected to concentrate in ambiguous handwritten digits and distribution shifts outside that input format.