Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,98 @@
+---
+license: mit
+library_name: pytorch
+pipeline_tag: image-classification
+tags:
+  - computer-vision
+  - image-classification
+  - mobilenet-v2
+  - cards
+  - solitaire
+  - computer-use
+datasets:
+  - solitaire-cards-dataset
+metrics:
+  - accuracy
+---
+
+# Solitaire Card Recognizer
+
+A 52-class playing-card classifier fine-tuned from **MobileNet v2** (ImageNet
+weights from `torchvision`). It was trained for an autonomous computer-use agent
+that plays Microsoft Solitaire Collection through the real screen and mouse:
+the agent sees only pixels, so this model is its "eyes".
+
+* **Accuracy:** 99.91 % (3251/3254) on the full dataset, **100 %** (650/650) on
+  the held-out split
+* **Size:** 2,290,484 parameters (9.4 MB, `model.pth`)
+* **Latency:** 6.7 ms pure inference, 8.1 ms including crop and preprocessing
+  (single crop, RTX 2060S); tens of milliseconds on CPU
+* **Input:** a full, fully visible card image (the training crops are 131×176 px;
+  the model resizes to 224×224 and applies ImageNet normalization)
+* **Output:** one of 52 classes in the order of `classes.json`
+  (`10_clubs … Q_spades`, matching `torchvision.datasets.ImageFolder` ordering)
+
+## Usage
+
+```python
+import json
+from huggingface_hub import hf_hub_download
+import torch, torchvision
+from PIL import Image
+from torchvision import transforms
+
+repo = "WildFuria/solitaire-card-recognizer"     # ← your namespace after upload
+weights = hf_hub_download(repo, "model.pth")
+classes = json.load(open(hf_hub_download(repo, "classes.json"), encoding="utf-8"))["classes"]
+
+model = torchvision.models.mobilenet_v2(weights=None)
+model.classifier[1] = torch.nn.Linear(model.classifier[1].in_features, len(classes))
+model.load_state_dict(torch.load(weights, map_location="cpu", weights_only=True))
+model.eval()
+
+tf = transforms.Compose([
+    transforms.Resize((224, 224)),
+    transforms.ToTensor(),
+    transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+])
+
+img = Image.open("card.png").convert("RGB")
+with torch.no_grad():
+    probs = torch.softmax(model(tf(img).unsqueeze(0)), dim=1)[0]
+rank_suit, idx = classes[int(probs.argmax())], int(probs.argmax())
+print(rank_suit, f"{float(probs[idx]):.3f}")
+```
+
+## Training data
+
+Collected and auto-labelled from live play: **3254 full cards (131×176 px)** in 52
+balanced classes, plus 3967 earlier corner crops (42×54 px) from the abandoned
+first pipeline. Published as
+[`solitaire-cards-dataset`](https://huggingface.co/datasets/solitaire-cards-dataset).
+Labels were produced semi-automatically (a local vision-language model plus manual
+sorting), so expect a small amount of label noise — the reported accuracy is
+measured against those labels, not against a human-audited test set.
+
+## Limitations
+
+* It expects a **whole card**, not a tiny corner crop. The older 42×54 corner
+  dataset (also published, folder `corners`) is out of distribution: a corner
+  crop fed to this model returns a wrong class with moderate confidence — the
+  corner pipeline was abandoned for exactly that reason.
+* Trained on the **Microsoft Solitaire Collection** card art at 1920×1040. Other
+  card designs, fonts or resolutions are out of distribution.
+* It expects a **fully visible card**. A partially overlapped card inside a fan
+  (only its top strip visible) is read unreliably — that is a data limitation, not
+  a code bug, and it is documented in the agent's engineering notes.
+* It classifies a single card crop; it does not detect cards on a full screenshot
+  (that geometry lives in the agent's `vision/` layer).
+
+## Links
+
+* Code, tests and the full agent: [solitaire-computer-agent](https://github.com/WildFuria/solitaire-computer-agent)
+* Interactive demo: [Space](https://huggingface.co/spaces/WildFuria/solitaire-card-recognizer-demo)
+* Case study: [ai-wiki.tech](https://ai-wiki.tech/en/cases/autonomous-computer-agent/)
+
+## License
+
+MIT. MobileNet v2 architecture comes from `torchvision` (BSD-3-Clause).