# Face to Identity Workflow Guide

> Version: V4.0 | Date: 2026-04-28
> Architecture: Two-layer (Face → Identity)
> Related: [FACE_TO_IDENTITY_FLOW.md](./FACE_TO_IDENTITY_FLOW.md)

---

## Overview

V4.0 架構實現 Face → Identity 直接綁定，移除 person_id 中間層，簡化工作流程。

### Key Changes (V3.x → V4.0)

| Change | V3.x | V4.0 |
|--------|------|------|
| **Architecture** | Three-layer (Face → Person → Identity) | Two-layer (Face → Identity) |
| **Person ID** | Video-local person_id | ❌ Removed |
| **Registration** | POST /identities/from-person | POST /identities/register |
| **Merge** | POST /person/merge | POST /agents/suggest/merge |
| **Candidates** | GET /person/list | GET /faces/candidates |
| **file_uuid** | Used everywhere | **file_uuid** |

---

## Workflow Visualization

```mermaid
graph TD
    %% Nodes
    Start((Start Analysis))
    ListCandidates[List Face Candidates]
    
    subgraph "Phase 1: Registration"
        CheckIdentity{Identity Exists?}
        Register[Register Identity]
        Bind[Bind Faces]
    end
    
    subgraph "Phase 2: AI Analysis"
        Suggest[Get AI Suggestions]
        Review[Review Suggestions]
        Merge[Execute Merge]
        Confirm[Confirm Result]
    end
    
    End((Database Clean))

    %% Flow
    Start --> ListCandidates
    ListCandidates --> CheckIdentity
    
    CheckIdentity -- No --> Register
    Register --> Bind
    Bind --> Suggest
    
    CheckIdentity -- Yes --> Bind
    Bind --> Suggest
    
    Suggest --> Review
    Review -- Merge Recommended --> Merge
    Review -- Bind Recommended --> Bind
    
    Merge --> Confirm
    Confirm --> End

    style Start fill:#f9f,stroke:#333
    style End fill:#bbf,stroke:#333
    style Register fill:#dfd,stroke:#333
    style Bind fill:#dfd,stroke:#333
```

---

## Phase 1: Registration

**Scenario**: You found unregistered faces and want to create a new identity.

### Step 1: List Face Candidates

```bash
curl -s "http://localhost:3003/api/v1/faces/candidates?min_confidence=0.8&pose_angle=frontal&limit=5" \
  -H "X-API-Key: YOUR_KEY"
```

**Response**:

```json
{
  "success": true,
  "data": {
    "candidates": [
      {
        "face_id": "face_100",
        "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
        "frame": 100,
        "timestamp": 5.2,
        "pose_angle": "frontal",
        "confidence": 0.92,
        "trace_id": 2
      }
    ],
    "statistics": {
      "total_candidates": 78,
      "avg_confidence": 0.85
    }
  }
}
```

### Step 2: Register Identity

```bash
curl -X POST "http://localhost:3003/api/v1/identities/register" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "face_ids": ["face_100", "face_150", "face_200"],
    "name": "Audrey Hepburn",
    "source": "manual",
    "auto_bind_chunks": true
  }'
```

**Response**:

```json
{
  "success": true,
  "data": {
    "identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
    "name": "Audrey Hepburn",
    "faces_bound": 3,
    "chunks_bound": 10,
    "speaker_ids": ["SPEAKER_0"],
    "reference_vectors": {
      "total": 3,
      "angles": ["frontal"]
    }
  }
}
```

---

## Phase 2: AI Analysis

**Scenario**: You want AI to suggest potential merges or additional bindings.

### Step 1: Get AI Suggestions

```bash
curl -X POST "http://localhost:3003/api/v1/agents/suggest/clustering" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "min_confidence": 0.8,
    "pose_angles": ["frontal"],
    "max_suggestions": 5
  }'
```

**Response**:

```json
{
  "success": true,
  "data": {
    "suggestions": [
      {
        "suggestion_id": "suggest_1",
        "cluster_type": "high_confidence",
        "confidence": 0.92,
        "recommended_faces": [
          {
            "face_id": "face_100",
            "pose_angle": "frontal",
            "confidence": 0.95,
            "is_primary": true
          }
        ],
        "cluster_stats": {
          "total_faces": 50,
          "avg_similarity": 0.89
        },
        "reason": "High confidence frontal faces from same trace",
        "action": "register"
      },
      {
        "suggestion_id": "suggest_2",
        "cluster_type": "existing_identity",
        "confidence": 0.88,
        "identity_uuid": "a9a90105...",
        "recommended_faces": [
          {
            "face_id": "face_300",
            "confidence": 0.87
          }
        ],
        "reason": "Similar to Audrey Hepburn (0.88)",
        "action": "bind"
      }
    ]
  }
}
```

### Step 2: Review & Execute

**Option A: Bind to Existing Identity**

```bash
curl -X POST "http://localhost:3003/api/v1/identities/a9a90105.../bind" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "face_ids": ["face_300", "face_400"],
    "auto_bind_chunks": true
  }'
```

**Option B: Register New Identity**

```bash
curl -X POST "http://localhost:3003/api/v1/identities/register" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "face_ids": ["face_500", "face_550"],
    "name": "Cary Grant",
    "source": "manual"
  }'
```

### Step 3: Merge Identities

**Scenario**: Two identities are the same person.

```bash
curl -X POST "http://localhost:3003/api/v1/agents/suggest/merge" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_uuids": ["a9a90105...", "b8b80206..."],
    "threshold": 0.85
  }'
```

**Response**:

```json
{
  "success": true,
  "data": {
    "suggestions": [
      {
        "suggestion_type": "merge",
        "confidence": 0.88,
        "identities": [
          {"identity_uuid": "a9a90105...", "name": "Person A", "face_count": 500},
          {"identity_uuid": "b8b80206...", "name": "Person B", "face_count": 300}
        ],
        "reason": "High embedding similarity (0.88)",
        "recommended_action": {
          "merge_target": "a9a90105...",
          "merge_sources": ["b8b80206..."]
        }
      }
    ]
  }
}
```

---

## Query Operations

### List Identities in a File

```bash
curl "http://localhost:3003/api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966/identities" \
  -H "X-API-Key: YOUR_KEY"
```

### List Files for an Identity

```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../files" \
  -H "X-API-Key: YOUR_KEY"
```

### List Faces for an Identity

```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../faces?limit=100" \
  -H "X-API-Key: YOUR_KEY"
```

### List Chunks for an Identity

```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../chunks" \
  -H "X-API-Key: YOUR_KEY"
```

---

## Demo Script

```bash
#!/bin/bash
# scripts/demo_identity_workflow_v4.sh

API_URL="http://localhost:3003"
API_KEY="YOUR_API_KEY"

echo "=== MOMENTRY IDENTITY WORKFLOW V4.0 ==="

# 1. List candidates
echo "STEP 1: Listing unregistered faces..."
curl -s "$API_URL/api/v1/faces/candidates?min_confidence=0.8&limit=5" \
  -H "X-API-Key: $API_KEY" \
  | python3 -m json.tool

# 2. Register identity
echo ""
echo "STEP 2: Registering Audrey Hepburn..."
curl -s -X POST "$API_URL/api/v1/identities/register" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"face_ids": ["face_100"], "name": "Audrey Hepburn", "source": "manual"}' \
  | python3 -m json.tool

# 3. Get AI suggestions
echo ""
echo "STEP 3: Getting AI suggestions..."
curl -s -X POST "$API_URL/api/v1/agents/suggest/clustering" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"min_confidence": 0.8, "max_suggestions": 3}' \
  | python3 -m json.tool

# 4. Bind faces to identity
echo ""
echo "STEP 4: Binding additional faces..."
curl -s -X POST "$API_URL/api/v1/identities/a9a90105.../bind" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"face_ids": ["face_200"]}' \
  | python3 -m json.tool

echo ""
echo "Demo Complete."
```

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| V4.0 | 2026-04-28 | Two-layer architecture, 15 endpoints |
| V3.x | 2026-04-10 | Three-layer architecture, 33 endpoints |

---

## Related Documents

- [IDENTITY_MANAGEMENT_API.md](./IDENTITY_MANAGEMENT_API.md): API design
- [FACE_TO_IDENTITY_FLOW.md](./FACE_TO_IDENTITY_FLOW.md): Binding flow
- [FILE_IDENTITIES_TABLE_SPEC.md](./FILE_IDENTITIES_TABLE_SPEC.md): Table schema
- [IDENTITY_API_SPEC.md](../IDENTITY_API_SPEC.md): Complete API spec
