miku-discord/FACE_DETECTION_API_MIGRATION.md

# Face Detection API Migration

## Overview
Migrated Miku bot's profile picture feature from local `anime-face-detector` library to external API service to resolve Python dependency conflicts.

## Changes Made

### 1. **Profile Picture Manager** (`bot/utils/profile_picture_manager.py`)

#### Removed:
- Local `anime-face-detector` library initialization
- Direct YOLOv3 model loading in bot process
- `self.face_detector` instance variable
- OpenCV image conversion for face detection

#### Added:
- API endpoint constant: `FACE_DETECTOR_API = "http://anime-face-detector:6078/detect"`
- HTTP client for face detection API calls
- Enhanced detection response parsing with bbox, confidence, and keypoints
- Health check on initialization to verify API availability

#### Updated Methods:

**`initialize()`**
- Now checks API health endpoint instead of loading local model
- Graceful fallback if API unavailable

**`_detect_face(image_bytes, debug)`**
- Changed signature from `(cv_image: np.ndarray)` to `(image_bytes: bytes)`
- Now sends multipart form-data POST to API
- Returns rich detection dict instead of simple tuple:
```python
{
    'center': (x, y),          # Face center coordinates
    'bbox': [x1, y1, x2, y2],  # Bounding box
    'confidence': 0.98,         # Detection confidence
    'keypoints': [...],         # 27 facial landmarks
    'count': 1                  # Number of faces detected
}
```

**`_intelligent_crop(image, image_bytes, target_size, debug)`**
- Added `image_bytes` parameter for API call
- Updated to use new detection dict format
- Falls back to saliency detection if API call fails

### 2. **Dependencies** (`bot/requirements.txt`)

#### Removed:
```
anime-face-detector
```

This library had conflicts with the bot's CUDA/PyTorch environment.

### 3. **Docker Networking** (`anime-face-detector-gpu/docker-compose.yml`)

#### Added:
```yaml
networks:
  miku-discord_default:
    external: true
```

Allows the face detector container to communicate with Miku bot container.

## Architecture

### Before (Monolithic):
```
┌─────────────────────────────┐
│      Miku Bot Container     │
│  ┌───────────────────────┐  │
│  │   anime-face-detector │  │ ❌ Dependency conflicts
│  │   YOLOv3 Model        │  │
│  └───────────────────────┘  │
│  Discord Bot Logic          │
└─────────────────────────────┘
```

### After (Microservices):
```
┌─────────────────────────────┐      ┌──────────────────────────────┐
│      Miku Bot Container     │      │ Face Detector API Container  │
│                             │      │                              │
│  HTTP Client ──────────────────────▶  FastAPI Endpoint           │
│  Discord Bot Logic          │      │  YOLOv3 Model (GPU)          │
│  Profile Picture Manager    │      │  anime-face-detector lib     │
└─────────────────────────────┘      └──────────────────────────────┘
         ▲                                       │
         │                                       │
         └───── JSON Response with detections ───┘
```

## API Endpoint

### Request:
```bash
POST http://anime-face-detector:6078/detect
Content-Type: multipart/form-data

file: <image_bytes>
```

### Response:
```json
{
  "detections": [
    {
      "bbox": [629.5, 408.4, 1533.7, 1522.5],
      "confidence": 0.9857,
      "keypoints": [
        [695.4, 644.5, 0.736],
        [662.7, 894.8, 0.528],
        ...
      ]
    }
  ],
  "count": 1,
  "annotated_image": "/app/api/outputs/image_..._annotated.jpg",
  "json_file": "/app/api/outputs/image_..._results.json"
}
```

## Benefits

✅ **Dependency Isolation**: Face detection library runs in dedicated container with its own Python environment
✅ **GPU Optimization**: Detector container uses CUDA-optimized YOLOv3
✅ **Easier Updates**: Can update face detection model without touching bot code
✅ **Better Debugging**: Gradio UI at port 7860 for visual testing
✅ **Scalability**: Multiple services could use the same face detection API
✅ **Graceful Degradation**: Bot continues working with saliency fallback if API unavailable

## Deployment Steps

### 1. Start Face Detector API
```bash
cd /home/koko210Serve/docker/anime-face-detector-gpu
docker-compose up -d
```

### 2. Verify API Health
```bash
curl http://localhost:6078/health
# Should return: {"status":"healthy","detector_loaded":true}
```

### 3. Rebuild Miku Bot (to remove old dependency)
```bash
cd /home/koko210Serve/docker/miku-discord
docker-compose build miku-bot
docker-compose up -d
```

### 4. Check Logs
```bash
# Bot should show:
docker-compose logs miku-bot | grep "face detector"
# Expected: "✅ Anime face detector API connected"
```

## Testing

### Test Face Detection Directly:
```bash
curl -X POST http://localhost:6078/detect \
  -F "file=@./images/test_miku.jpg" | jq .
```

### Test Profile Picture Change:
```bash
# Via API
curl -X POST "http://localhost:8000/profile-picture/change"

# Or via web UI
# Navigate to http://localhost:8000 → Actions → Profile Picture
```

## Troubleshooting

### "Face detector API not available"
- Check if container is running: `docker ps | grep anime-face-detector`
- Check network: `docker network ls | grep miku-discord`
- Verify API responds: `curl http://localhost:6078/health`

### "No faces detected"
- Check API logs: `docker-compose -f anime-face-detector-gpu/docker-compose.yml logs`
- Test with Gradio UI: http://localhost:7860
- Bot will fallback to saliency detection automatically

### Network Issues
If containers can't communicate:
```bash
# Ensure miku-discord network exists
docker network inspect miku-discord_default

# Reconnect anime-face-detector container
cd anime-face-detector-gpu
docker-compose down
docker-compose up -d
```

## Future Enhancements

Potential improvements now that we have a dedicated API:

1. **Batch Processing**: Detect faces in multiple images simultaneously
2. **Face Recognition**: Add character identification (not just detection)
3. **Expression Analysis**: Determine mood from detected faces
4. **Quality Scoring**: Rate image quality for better selection
5. **Custom Models**: Easy to swap YOLOv3 for newer models
6. **Caching**: Store detection results to avoid reprocessing

## Files Modified

- ✏️ `/miku-discord/bot/utils/profile_picture_manager.py` - API integration
- ✏️ `/miku-discord/bot/requirements.txt` - Removed anime-face-detector
- ✏️ `/anime-face-detector-gpu/docker-compose.yml` - Added network config

## Documentation

- 📄 Face Detector API docs: `/anime-face-detector-gpu/README_API.md`
- 📄 Setup guide: `/anime-face-detector-gpu/SETUP_COMPLETE.md`
- 📄 Profile picture feature: `/miku-discord/PROFILE_PICTURE_IMPLEMENTATION.md`