feat: trace quality agent selection report, identity clustering runner_v2 DB write, age/gender CoreML selection, updated experiment config UUID

docs_v1.0/API_V1.0.0/INTERNAL/TRACE_QUALITY_AGENT_REPORT_V1.0.0.md

@@ -0,0 +1,84 @@
+---
+document_type: "experiment_report"
+service: "MOMENTRY_CORE"
+title: "Trace 品質檢查 Agent 選型報告"
+date: "2026-05-06"
+version: "V1.0"
+status: "completed"
+---
+
+# Trace 品質檢查 Agent 選型報告
+
+## 1. 目標
+
+在 identity clustering pipeline 前，對每個 trace 進行品質檢查：
+
+| Check | 說明 | 技術 | 依賴 |
+|-------|------|------|------|
+| 取樣密度 | < 4 frames → dense scan | SQL + swift_face | Apple Vision |
+| 人臉驗證 | 確認是否為人類 | DeepFace / Apple Vision | 見第 3 節 |
+| Embedding 品質 | variance > 0.2 → split | numpy statistics | 無 |
+| 時序衝突 | 同 identity 同時出現 | SQL JOIN | 無 |
+
+## 2. Check 1: 取樣密度
+
+Charade 實測：1886/2347 traces (80.4%) < 4 frames。
+
+**建議**: 對少於 4 frames 的 trace，自動排程 swift_face dense scan（`--sample-interval 1`），時間窗為 trace 的 ±2 秒。
+
+## 3. Check 2: 人臉驗證
+
+### 3.1 現有方案測試
+
+DeepFace 對 10 個 trace（含最低信心 0.58）全部回傳 human。Apple Vision 的 face detection 沒有 false positive。
+
+### 3.2 Age/Gender 模型選型
+
+| 方案 | 技術 | License | 狀態 |
+|------|------|---------|------|
+| A | CoreML 轉換 (yu4u) | MIT | ⚠️ coremltools 相依性衝突 |
+| B | Create ML 自訓練 | Apple | 需 ~10GB 訓練資料 |
+| **C** | **DeepFace** | **MIT** | **✅ 已安裝，5.5s/10faces** |
+| D | Apple Vision heuristic | System | ✅ 已整合（無 age/gender） |
+
+### 3.3 建議
+
+**短期**: 方案 C (DeepFace)，立即可用，已通過 10-face 測試。
+**長期**: 方案 A (CoreML)，解決 coremltools 版本衝突後可去除 Python 依賴。
+
+Pipeline 整合位置：
+
+```
+swift_face → store_traced_faces → TraceQualityAgent → identity_clustering
+                                      ├─ Check 1: SQL (instant)
+                                      ├─ Check 2: DeepFace (0.6s/face)
+                                      ├─ Check 3: numpy (instant)
+                                      └─ Check 4: SQL (instant)
+```
+
+## 4. Check 3: Embedding 品質
+
+實測 top 10 traces 的 intra-trace embedding variance:
+
+| trace | faces | variance | 判定 |
+|-------|-------|----------|------|
+| 0 | 45 | 0.041 | ✅ good |
+| 1342 | 34 | 0.333 | ❌ split |
+| 1340 | 29 | 0.334 | ❌ split |
+
+**Rule**: variance > 0.2 OR min_sim < 0.4 → 標記 needs_split。
+
+## 5. Check 4: 時序衝突
+
+發現 Audrey Hepburn 的 trace 39 和 trace 45 出現在同一幀 → 不可能為同一人。
+
+**Rule**: 同一 identity 的兩個 trace 時間重疊 → 需 split。
+
+## 6. 總結
+
+| 檢查 | 自動化 | 需模型 |
+|------|--------|--------|
+| 取樣密度 | ✅ 全自動 | ✅ Apple Vision |
+| 人臉驗證 | ✅ 全自動 | ⚠️ DeepFace (暫) |
+| Embedding 品質 | ⚠️ 標記需手動審查 | ❌ |
+| 時序衝突 | ⚠️ 標記需手動審查 | ❌ |