Upload README.md

README.md

@@ -1,28 +1,70 @@
+---
+title: CIFAR-100 ResNet18 Classifier
+emoji: 🚀
+colorFrom: indigo
+colorTo: purple
+sdk: gradio
+app_file: app.py
+pinned: false
+license: apache-2.0
+---
+
 # ResNet on CIFAR-100
 
-This project trains a ResNet model from scratch on the CIFAR-100 dataset.
+Train a ResNet18 from scratch on CIFAR-100 and deploy a Gradio demo on Hugging Face Spaces.
 
 ## Target
 
-- Achieve 73% top-1 accuracy on CIFAR-100.
-- No pre-trained models are used.
+- Achieve ≥ 73% top-1 accuracy on CIFAR-100
+- Train from scratch (no pretrained weights)
 
 ## Project Structure
 
-- `main.py`: Main script to train the model.
-- `model.py`: ResNet model implementation.
-- `utils.py`: Data loading, augmentations, and other utilities.
-- `logs.md`: Training logs.
+- `main.py`: Training entrypoint (OneCycleLR + label smoothing)
+- `model.py`: ResNet18 architecture (with dropout)
+- `utils.py`: CIFAR-100 dataloaders and augmentations (RandAugment + RandomErasing)
+- `app.py`: Gradio Space app (CPU inference, loads `ckpt.pth` if present)
+- `logs.md`: Training logs (epoch-by-epoch)
+- `.gitattributes`: Git LFS rules for weight files (`.pth`, `.pt`)
+- `requirements.txt`: Dependencies
+
+## Train
+
+1) Install deps
+```bash
+pip install -r requirements.txt
+```
 
-## How to run
+2) Run training
+```bash
+python main.py --lr 0.2 --epoch 70
+```
+- Best checkpoint auto-saves as `ckpt.pth`
+- Logs are written to `logs.md`
 
-1. Install dependencies: `pip install -r requirements.txt`
-2. Run training: `python main.py`
+Tips:
+- You can stop early once test accuracy ≥ 73% (best weights already saved)
+- For Apple Silicon: code auto-uses `mps` if available
 
-## Hugging Face Spaces
+## Export / Weights
+- Keep the best weights at repo root as `ckpt.pth` (tracked via LFS)
+- `app.py` will attempt to load one of: `ckpt.pth`, `checkpoint/resnet18_cifar100.pth`, `resnet18_cifar100.pth`
+- If your checkpoint is a dict with `net` (current default), no change needed
 
-[Link to be added]
+## Deploy to Hugging Face Spaces
+1) Create a new Space (SDK: Gradio)
+2) Push these files at minimum:
+   - `app.py`, `model.py`, `utils.py`, `requirements.txt`, `.gitattributes`
+   - `ckpt.pth` (LFS)
+3) The app runs CPU-only and resizes inputs to 32×32. It returns top-5 predictions.
 
-## GitHub
+## Local Demo
+```bash
+python app.py
+```
+Open the printed local Gradio URL in your browser, upload an image, and view predictions.
 
-[Link to be added]
+## Links
+- Space: [link to be added]
+- GitHub: [link to be added]
+- Logs: `logs.md`