Upload README.md with huggingface_hub

README.md

@@ -1,10 +1,128 @@
 ---
-title: MilkSpoilageClassifier API Variants
-emoji: 🔥
-colorFrom: purple
-colorTo: indigo
+title: Milk Spoilage Classifier - Multi-Variant API
+emoji: 🥛
+colorFrom: indigo
+colorTo: purple
 sdk: docker
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Milk Spoilage Classification API - Multi-Variant
+
+AI-powered milk spoilage classification with **10 specialized model variants** optimized for different data availability scenarios.
+
+## 🚀 Features
+
+- **10 Model Variants** with test accuracies from 62.8% to 95.8%
+- **Automatic Feature Validation** - API validates required features for each variant
+- **RESTful API** with comprehensive OpenAPI documentation
+- **Custom GPT Ready** - Designed for seamless ChatGPT integration
+
+## 📊 Available Model Variants
+
+| Rank | Variant | Test Accuracy | Features Required |
+|------|---------|---------------|-------------------|
+| 🥇 | baseline | **95.8%** | All 6 features |
+| 🥈 | scenario_1_days14_21 | **94.2%** | Days 14 & 21 (SPC+TGN) |
+| 🥉 | scenario_3_day21 | **93.7%** | Day 21 only (SPC+TGN) |
+| 4 | scenario_4_day14 | 87.4% | Day 14 only (SPC+TGN) |
+| 5 | scenario_2_days7_14 | 87.3% | Days 7 & 14 (SPC+TGN) |
+| 6 | scenario_6_spc_all | 78.3% | SPC only (All Days) |
+| 7 | scenario_8_spc_7_14 | 73.3% | SPC only (Days 7 & 14) |
+| 8 | scenario_9_tgn_7_14 | 73.1% | TGN only (Days 7 & 14) |
+| 9 | scenario_7_tgn_all | 69.9% | TGN only (All Days) |
+| 10 | scenario_5_day7 | 62.8% | Day 7 only (SPC+TGN) |
+
+## 🔧 API Endpoints
+
+### `GET /variants`
+List all available model variants with metadata
+
+### `POST /predict`
+Make a prediction using the specified model variant
+
+**Example Request:**
+```json
+{
+  "spc_d7": 2.1,
+  "spc_d14": 4.7,
+  "spc_d21": 6.4,
+  "tgn_d7": 1.0,
+  "tgn_d14": 3.7,
+  "tgn_d21": 5.3,
+  "model_variant": "baseline"
+}
+```
+
+**Example Response:**
+```json
+{
+  "prediction": "PPC",
+  "probabilities": {
+    "PPC": 0.97,
+    "no spoilage": 0.02,
+    "spore spoilage": 0.01
+  },
+  "confidence": 0.97,
+  "variant_used": {
+    "variant_id": "baseline",
+    "name": "Baseline (All Features)",
+    "test_accuracy": 0.9576,
+    "features": ["SPC_D7", "SPC_D14", "SPC_D21", "TGN_D7", "TGN_D14", "TGN_D21"]
+  }
+}
+```
+
+## 📖 Spoilage Classes
+
+| Class | Description |
+|-------|-------------|
+| **PPC** | Post-Pasteurization Contamination - Bacteria introduced after pasteurization |
+| **no spoilage** | No significant spoilage detected |
+| **spore spoilage** | Heat-resistant spore-forming bacteria survived pasteurization |
+
+## 🔗 Interactive Documentation
+
+Visit `/docs` for interactive Swagger UI documentation where you can test the API directly.
+
+## 💻 Usage Example
+
+```bash
+curl -X POST https://chenhaoq87-milkspoilageclassifier-api-variants.hf.space/predict \
+  -H "Content-Type: application/json" \
+  -d '{
+    "spc_d21": 6.4,
+    "tgn_d21": 5.3,
+    "model_variant": "scenario_3_day21"
+  }'
+```
+
+## 🤖 Custom GPT Integration
+
+This API is designed for Custom GPT integration. The GPT will automatically select the best variant based on available data.
+
+See the [Custom GPT Setup Guide](https://huggingface.co/chenhaoq87/MilkSpoilageClassifier/blob/main/docs/CUSTOM_GPT_SETUP_MULTIVARIANT.md) for complete integration instructions.
+
+## 📝 Input Format
+
+All microbial count values should be in **log CFU/mL (base 10)**:
+- **SPC** (Standard Plate Count): Total bacterial count
+- **TGN** (Total Gram-Negative): Gram-negative bacteria count
+- Measured at **Day 7, 14, and 21**
+
+## 🔍 Variant Selection Guide
+
+- **Have all measurements?** → Use `baseline` (best accuracy)
+- **Only Day 21 data?** → Use `scenario_3_day21` (nearly as good!)
+- **Only Day 14 data?** → Use `scenario_4_day14`
+- **Only SPC measurements?** → Use `scenario_6_spc_all`
+- **Only TGN measurements?** → Use `scenario_7_tgn_all`
+
+## 📚 Research
+
+Based on predictive modeling for milk spoilage classification using microbial growth patterns.
+
+---
+
+**Model Repository:** [MilkSpoilageClassifier](https://huggingface.co/chenhaoq87/MilkSpoilageClassifier)