Update README.md

README.md

@@ -1,3 +1,59 @@
 ---
 license: mit
+tags:
+  - image-classification
+  - pytorch
+  - resnet18
+  - butterflies
 ---
+
+# ButterflyID_5class
+
+**ButterflyID_5class** is an image classification model that identifies 5 butterfly species commonly observed in Missouri: Black Swallowtail, Common Buckeye, Eastern Tiger Swallowtail, Red-Spotted Purple, and Small White. Built with PyTorch using transfer learning on a fine-tuned ResNet18 backbone.
+
+This is a v1 release — the species list is intentionally limited for now and is planned to expand over time. These species are not exclusive to Missouri; the dataset was simply built around locally available observations.
+
+## Performance
+
+Dataset split: 177 train / 35 val / 44 test images across 5 classes.
+
+- **Best validation accuracy:** 94.29%
+- **Final test accuracy:** 90.91%
+
+**Per-class test accuracy:**
+
+| Species | Accuracy |
+|---|---|
+| Common Buckeye | 100.00% (9/9) |
+| Red-Spotted Purple | 100.00% (9/9) |
+| Small White | 100.00% (9/9) |
+| Eastern Tiger Swallowtail | 88.89% (8/9) |
+| Black Swallowtail | 62.50% (5/8) |
+
+Black Swallowtail is the model's weakest class, likely due to visual similarity with Eastern Tiger Swallowtail (both swallowtail species with overlapping wing shape/pattern features). Test set sizes are small (8-9 images per class), so individual misclassifications have a large effect on the reported percentage.
+
+## Data
+
+Training images were sourced from [iNaturalist](https://www.inaturalist.org/). Full data attribution and licensing details are available in ATTRIBUTIONS.md in the project repo.
+
+## Usage
+
+This checkpoint bundles both the trained model weights and the class name list together:
+
+```python
+import torch
+from torchvision import models
+import torch.nn as nn
+
+checkpoint = torch.load("butterfly_model.pt", map_location="cpu")
+class_names = checkpoint["class_names"]
+
+model = models.resnet18(weights=None)
+model.fc = nn.Linear(model.fc.in_features, len(class_names))
+model.load_state_dict(checkpoint["model_state_dict"])
+model.eval()
+```
+
+## Project
+
+Part of the full-stack [ButterflyID project](https://github.com/devbyjen388/ButterflyID) (FastAPI backend + web frontend).