docs/API_DOCUMENTATION.md

# REST API for Custom GPT

## Endpoint

```
POST https://chenhaoq87-milkspoilageclassifier-demo.hf.space/api/predict
```

## OpenAPI Schema for Custom GPT Actions

Copy this into your Custom GPT's Action configuration:

```yaml
openapi: 3.1.0
info:
  title: Milk Spoilage Classification API
  version: 1.0.0
  description: Predict milk spoilage type based on microbial count data
servers:
  - url: https://chenhaoq87-milkspoilageclassifier-demo.hf.space
paths:
  /api/predict:
    post:
      operationId: classifyMilkSpoilage
      summary: Predict milk spoilage type
      description: |
        Classifies milk spoilage into three categories based on Standard Plate Count (SPC) 
        and Total Gram-Negative (TGN) bacterial measurements at days 7, 14, and 21.
        All values should be in log CFU/mL format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - spc_d7
                - spc_d14
                - spc_d21
                - tgn_d7
                - tgn_d14
                - tgn_d21
              properties:
                spc_d7:
                  type: number
                  description: Standard Plate Count at Day 7 (log CFU/mL)
                  minimum: 0
                  maximum: 10
                  example: 4.0
                spc_d14:
                  type: number
                  description: Standard Plate Count at Day 14 (log CFU/mL)
                  minimum: 0
                  maximum: 10
                  example: 5.0
                spc_d21:
                  type: number
                  description: Standard Plate Count at Day 21 (log CFU/mL)
                  minimum: 0
                  maximum: 10
                  example: 6.0
                tgn_d7:
                  type: number
                  description: Total Gram-Negative at Day 7 (log CFU/mL)
                  minimum: 0
                  maximum: 10
                  example: 3.0
                tgn_d14:
                  type: number
                  description: Total Gram-Negative at Day 14 (log CFU/mL)
                  minimum: 0
                  maximum: 10
                  example: 4.0
                tgn_d21:
                  type: number
                  description: Total Gram-Negative at Day 21 (log CFU/mL)
                  minimum: 0
                  maximum: 10
                  example: 5.0
      responses:
        '200':
          description: Successful prediction
          content:
            application/json:
              schema:
                type: object
                properties:
                  prediction:
                    type: string
                    description: "Predicted class: PPC, no spoilage, or spore spoilage"
                    example: "PPC"
                  probabilities:
                    type: object
                    description: Probability for each class
                    additionalProperties:
                      type: number
                    example:
                      PPC: 0.85
                      no spoilage: 0.10
                      spore spoilage: 0.05
                  confidence:
                    type: number
                    description: Confidence score (highest probability)
                    example: 0.85
        '422':
          description: Validation error - invalid input values
```

## Authentication

No authentication required for this endpoint.

## Example Usage

### cURL
```bash
curl -X POST https://chenhaoq87-milkspoilageclassifier-demo.hf.space/api/predict \
  -H "Content-Type: application/json" \
  -d '{
    "spc_d7": 4.0,
    "spc_d14": 5.0,
    "spc_d21": 6.0,
    "tgn_d7": 3.0,
    "tgn_d14": 4.0,
    "tgn_d21": 5.0
  }'
```

### Python
```python
import requests

url = "https://chenhaoq87-milkspoilageclassifier-demo.hf.space/api/predict"
data = {
    "spc_d7": 4.0,
    "spc_d14": 5.0,
    "spc_d21": 6.0,
    "tgn_d7": 3.0,
    "tgn_d14": 4.0,
    "tgn_d21": 5.0
}

response = requests.post(url, json=data)
print(response.json())
```

## Response Format

```json
{
  "prediction": "PPC",
  "probabilities": {
    "PPC": 0.8523,
    "no spoilage": 0.1021,
    "spore spoilage": 0.0456
  },
  "confidence": 0.8523
}
```

## Class Descriptions

- **PPC**: Post-Pasteurization Contamination - bacteria introduced after pasteurization
- **no spoilage**: No significant spoilage detected
- **spore spoilage**: Spoilage from spore-forming bacteria that survived pasteurization

## Additional Endpoints

- **API Documentation**: https://chenhaoq87-milkspoilageclassifier-demo.hf.space/docs
- **Health Check**: https://chenhaoq87-milkspoilageclassifier-demo.hf.space/api/health
- **Interactive UI**: https://chenhaoq87-milkspoilageclassifier-demo.hf.space/