README.md

---
title: Milk Spoilage Classifier - Multi-Variant API
emoji: 🥛
colorFrom: indigo
colorTo: purple
sdk: docker
pinned: false
license: mit
---

# 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)