docs: update identity clustering report with TMDb direct match vs iterative enrichment analysis

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

@@ -1,84 +1,84 @@
 ---
 document_type: "experiment_report"
 service: "MOMENTRY_CORE"
-title: "Trace 品質檢查 Agent 選型報告"
+title: "Identity Clustering Agent 研究報告（含品質檢查 + 綁定分析）"
 date: "2026-05-06"
-version: "V1.0"
+version: "V1.1"
 status: "completed"
 ---
 
-# Trace 品質檢查 Agent 選型報告
+# Identity Clustering Agent 研究報告
 
-## 1. 目標
+## 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 整合位置：
+Runner 採用雙階段策略：
 
 ```
-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)
+             ┌── Stage 1: TMDb Direct Match ──┐
+             │  來源: identities.face_embedding │
+             │  模型: CoreML FaceNet 512-dim   │
+             │  門檻: face_sim ≥ 0.55          │
+             │  條件: ≥60% faces match         │
+             │  結果: 294 traces (43.4%)       │
+             └────────────────────────────────┘
+                          │
+                          ▼
+             ┌── Stage 1b: Iterative Enrichment ─┐
+             │  來源: bound trace multi-angle ref │
+             │  機制: 每 trace 取 top-3 faces    │
+             │  門檻: composite ≥ 0.50           │
+             │  下限: min_face_similarity ≥ 0.30 │
+             │  Round 1: 196 traces → Round 5: 1 │
+             │  結果: 363 traces (53.6%)         │
+             └───────────────────────────────────┘
+                          │
+                          ▼
+             ┌── Stage 2: Centroid Clustering ──┐
+             │  剩餘 trace 用 adaptive threshold │
+             │  結果: 20 traces grouped         │
+             └───────────────────────────────────┘
 ```
 
-## 4. Check 3: Embedding 品質
+**總覆蓋率**: 677/677 traces (100%)，其中 657 traces bound to 8 TMDb identities，20 traces clustered。
 
-實測 top 10 traces 的 intra-trace embedding variance:
+## 2. TMDb Direct Match vs Iterative Enrichment
 
-| trace | faces | variance | 判定 |
-|-------|-------|----------|------|
-| 0 | 45 | 0.041 | ✅ good |
-| 1342 | 34 | 0.333 | ❌ split |
-| 1340 | 29 | 0.334 | ❌ split |
+| 特性 | Stage 1 (TMDb) | Stage 1b (Iterative) |
+|------|---------------|---------------------|
+| 參考來源 | identities.face_embedding | bound trace faces |
+| embedding 品質 | TMDb 官方照片（單一視角） | 影片中 multi-angle（3 視角） |
+| 門檻 | 0.55 face_sim + 0.60 ratio | 0.50 composite + 0.30 min_sim |
+| 受門檻修正影響 | ❌ 否 | ✅ 是（0.35→0.50） |
+| 精準度 | 高（TMDb 照片 = ground truth） | 中（可能汙染，參考 RCA） |
+| traces bound | 294 (43.4%) | 363 (53.6%) |
+| 風險 | 低 | 汙染擴散（RCA: trace 39/45） |
 
-**Rule**: variance > 0.2 OR min_sim < 0.4 → 標記 needs_split。
+## 3. Trace 品質檢查
 
-## 5. Check 4: 時序衝突
+### 3.1 取樣密度檢查
 
-發現 Audrey Hepburn 的 trace 39 和 trace 45 出現在同一幀 → 不可能為同一人。
+1886/2347 traces (80.4%) < 4 frames。需 swift_face dense scan。
 
-**Rule**: 同一 identity 的兩個 trace 時間重疊 → 需 split。
+### 3.2 人臉驗證
 
-## 6. 總結
+DeepFace 測試 10 traces 全為 human。Apple Vision confidence + landmarks 可替代 DeepFace。
 
-| 檢查 | 自動化 | 需模型 |
-|------|--------|--------|
-| 取樣密度 | ✅ 全自動 | ✅ Apple Vision |
-| 人臉驗證 | ✅ 全自動 | ⚠️ DeepFace (暫) |
-| Embedding 品質 | ⚠️ 標記需手動審查 | ❌ |
-| 時序衝突 | ⚠️ 標記需手動審查 | ❌ |
+### 3.3 Embedding 品質
+
+Top 10 traces intra-trace variance: 從 0.041 (excellent) 到 0.334 (likely split)。
+
+### 3.4 時序碰撞
+
+修復前: Audrey Hepburn 有 114 處同 identity 碰撞。  
+修復後: threshold 0.35→0.50 + min_sim 0.30，碰撞歸零。
+
+## 4. 修復後整體影響
+
+| 指標 | 修復前 | 修復後 | Δ |
+|------|--------|--------|-----|
+| DB writes | 4059 | 3971 | -88 |
+| Coverage | 99.4% | 99.4% | — |
+| Collision (Audrey) | 114 | 0 | -114 |
+| Avg composite threshold | 0.35 | 0.50 | +0.15 |
+| Min face similarity guard | 無 | 0.30 | new |
+DOC