Moxieeixom/subtlety-detector-backend

SubtletyDetector Backend

FastAPI service that classifies facial emotions from a cropped face image.

Quick start (local)

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python app.py
# → http://localhost:7860

Endpoints

Method	Path	Body	Returns
GET	/health	—	Service & model status
GET	/emotions	—	Canonical 8-emotion list
POST	/predict	multipart/form-data field file=@face.jpg	8 emotion probabilities
POST	/predict_json	{"image": "data:image/jpeg;base64,..."}	8 emotion probabilities

Response shape

{
  "emotions": [
    {"key": "neutral", "label_en": "neutral", "label_zh": "平静", "emoji_mild": "😐", "emoji_strong": "😐", "probability": 0.12},
    ...
    {"key": "happy", ...}
  ],
  "top_emotion": "happy",
  "top_probability": 0.78,
  "inference_ms": 142.5
}

Swapping the model

The default is trpakov/vit-face-expression (7-class). To use a 8-class AffectNet model:

1. Set SUBTLETY_MODEL_ID=your-org/your-model as an env var, or
2. Edit inference.py → DEFAULT_MODEL_ID
3. Update emotions.py → TRPAKOV_IDX_TO_EMOTION to match the new model's output order (or replace _remap_to_8() to copy directly)

Deploy to Hugging Face Spaces

1. Create a Space with Docker SDK
2. Push this backend/ folder to the Space's repo
3. The Dockerfile will:
   • Install deps
   • Pre-download the model into the image
   • Expose port 7860

Free CPU tier gives 2 vCPU / 16 GB RAM — enough for ~150ms inference per request on a 224×224 face crop.