Update README.md

README.md

@@ -1,13 +1,96 @@
 ---
 title: Retail Shelf Detection
-emoji: 🐢
-colorFrom: purple
-colorTo: pink
+emoji: 🛒
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
 sdk_version: 6.16.0
 python_version: '3.13'
 app_file: app.py
 pinned: false
+license: mit
+short_description: YOLOv8 retail shelf product detection and compliance scoring
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🛒 Retail Shelf Detection — AI Prototype
+
+An AI-powered retail shelf analysis tool built with **YOLOv8 + Gradio**.  
+Upload a shelf photo taken by a field rep → model detects every product → compliance score is calculated automatically.
+
+---
+
+## 🚀 How to Use
+
+1. Upload a shelf photo (JPG or PNG)
+2. Adjust the **Confidence %** slider — lower means more detections
+3. Set your **Compliance threshold %** — the minimum fill rate to pass
+4. Click **Run Detection**
+
+The model draws bounding boxes around every product and tells you whether the shelf is compliant.
+
+---
+
+## 📊 What It Detects
+
+| Detection | Meaning |
+|---|---|
+| **Products on shelf** | Items present and correctly stocked |
+| **Empty slots** | Out-of-stock or missing products |
+| **Shelf fill rate** | Products ÷ (Products + Empty) × 100 |
+| **Compliance status** | ✅ Compliant if fill rate ≥ threshold |
+
+---
+
+## 🧠 Model
+
+| Detail | Info |
+|---|---|
+| Architecture | YOLOv8s (small) |
+| Fine-tuned on | Roboflow Retail Shelf Detection dataset |
+| Training | 50 epochs, 640×640 input size |
+| Task | Object detection — product presence & counting |
+
+---
+
+## 📁 Files in This Space
+
+```
+app.py              ← Gradio application
+requirements.txt    ← Python dependencies  
+best.pt             ← Fine-tuned YOLOv8s model weights
+README.md           ← This file
+```
+
+---
+
+## ⚙️ Sliders Explained
+
+**Confidence % (default: 30%)**  
+How certain the model must be before drawing a box.  
+- Lower → more boxes, catches more products but may include false positives  
+- Higher → fewer boxes, only high-confidence detections  
+
+**Compliance threshold % (default: 70%)**  
+The minimum shelf fill rate the client requires.  
+- If fill rate ≥ threshold → ✅ COMPLIANT  
+- If fill rate < threshold → ❌ NON-COMPLIANT  
+
+---
+
+## 🏗️ Part of the Retail Field Execution AI Platform
+
+This prototype demonstrates the **core detection engine**. The full production system adds:
+
+- 🏷️ SKU-level classification (Pepsi vs Coke vs Lays by name)
+- 📌 POSM detection (posters, danglers, shelf units, CTUs)
+- 📈 Execution dashboard with sales hierarchy rollups
+- 🗺️ Store coverage and customer coverage metrics
+- 🔍 Full audit trail — every compliance % links back to source image
+
+---
+
+## 🛠️ Built With
+
+- [Ultralytics YOLOv8](https://github.com/ultralytics/ultralytics)
+- [Gradio](https://gradio.app)
+- [Roboflow](https://roboflow.com) — dataset and labeling