---
document_type: "spec"
service: "MOMENTRY_CORE"
title: "Identity Agent v1.0.0"
date: "2026-05-07"
version: "V1.0"
status: "active"
owner: "Warren"
tags:
  - "momentry"
  - "agent"
  - "identity"
  - "face"
  - "speaker"
related_documents:
  - "../DATA_SCHEMA_FILE_IDENTITY_V1.0.0.md"
  - "../../TRACE/TRACE_API_REFERENCE_V1.0.0.md"
  - "../PROCESSORS/FACE_V1.0.0.md"
  - "../PROCESSORS/ASRX_V1.0.0.md"
---

# Identity Agent v1.0.0

## 概述

將 face trace 與 speaker 綁定到人物身份（identity），實現跨場景的人員辨識。

## 處理流程

```
face_clustered.json + asrx.json
  → extract_persons (face clusters)
  → extract_speakers (ASRX segments)
  → analyze_person_speaker_overlap
  → 寫入 dev.identities
  → match_faces_iterative (TMDb seed → propagation)
  → bind_speakers (speaker_id → identity_id)
```

## 迭代多角度 Face Matching

```
TMDb seeds (12 identities, with mulitple angles)
  → Round 1: ~33% trace-to-identity
  → Round 2: propagate matched traces as new seeds
  → Round 3: propagate again
  → Final: 99% binding (6,175 / 6,186 face detections)
```

## Speaker Binding

```
face_detections (trace_id, frame_number)
  + ASRX segments (speaker_id, start_time, end_time)
  → frame-level overlap computation
  → winner-takes-all: best_overlap > 30%
  → 寫入 identity_bindings (identity_type='speaker')
```

## Pipeline 觸發

Job Worker 中的 P3 trigger：

```rust
// has_face + has_asrx → run_identity_agent(db, uuid)
```

觸發時機：all_completed，face 與 asrx 皆完成後。

## DB 結構

| Table | 用途 |
|-------|------|
| `identities` | 身份主表（name, type, metadata, embedding） |
| `identity_bindings` | 綁定表（identity_id → trace_id 或 speaker_id） |
| `file_identities` | 檔案級身份對應 |

## API

```
POST /api/v1/agents/identity/analyze
POST /api/v1/agents/identity/suggest
GET  /api/v1/agents/identity/status
```
