init face embedding service

README.md

@@ -0,0 +1,71 @@
+# SMAN 1 Garut – Face Embedding Service
+
+Layanan Python kecil untuk menghasilkan **embedding wajah** + metrik kualitas yang dipakai backend CI4 (`FaceService`).
+
+## Fitur
+
+- Framework: **FastAPI** + **InsightFace**.
+- Endpoint utama: `POST /embed` (single image → embedding + quality).
+- Deteksi wajah, pilih wajah terbesar, hitung:
+  - `embedding` (vector float, default dimensi 512),
+  - `faces_count`,
+  - `face_size` (px),
+  - `blur` (variance of Laplacian),
+  - `brightness` (0..1),
+  - `quality_score` (kombinasi sederhana dari metrik di atas).
+
+## Setup Cepat
+
+```bash
+cd face-service
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+
+uvicorn main:app --host 0.0.0.0 --port 5000
+```
+
+Lalu di `.env` backend CI4 (`backend/.env`), set:
+
+```ini
+FACE_SERVICE_URL = 'http://localhost:5000'
+FACE_EMBEDDING_DIM = 512
+FACE_SIM_THRESHOLD = 0.85
+FACE_MIN_SIZE = 80
+FACE_MIN_BLUR = 30
+FACE_MIN_BRIGHTNESS = 0.2
+```
+
+## Kontrak API: `POST /embed`
+
+**Request** (multipart/form-data):
+
+- Field `image`: file gambar (.jpg/.png).
+
+**Response** (`200 OK`, JSON):
+
+```json
+{
+  "embedding": [0.01, -0.23, ...],
+  "quality_score": 0.93,
+  "faces_count": 1,
+  "face_size": 120.5,
+  "blur": 45.2,
+  "brightness": 0.55
+}
+```
+
+Backend CI4 (`FaceService::extractEmbeddingWithQuality`) akan:
+
+- Menolak gambar dengan:
+  - `faces_count != 1`,
+  - `face_size < FACE_MIN_SIZE`,
+  - `blur < FACE_MIN_BLUR`,
+  - `brightness < FACE_MIN_BRIGHTNESS`.
+
+## Health Check
+
+`GET /health` → `{"status": "ok", "model": "buffalo_l"}`
+
+Dipakai untuk cek cepat apakah service sudah siap dipakai backend CI4.
+