# Face / Speaker / Person / Identity Workflow Guide

This document describes the end-to-end workflow for managing characters in Momentry Core, from raw detection to a clean, aggregated identity database.

## 📊 1. Workflow Visualization

```mermaid
graph TD
    %% Nodes
    Start((Start Analysis))
    ListPersons[List Persons]
    
    subgraph "Phase 1: Registration"
        CheckIdentity{Identity Exists?}
        Register[Register Identity]
        Link[Link Person to Identity]
    end
    
    subgraph "Phase 2: Aggregation"
        Suggest[Get AI Suggestions]
        Review[Review Suggestions]
        Merge[Execute Merge]
        Confirm[Confirm Result]
    end
    
    End((Database Clean))

    %% Flow
    Start --> ListPersons
    ListPersons --> CheckIdentity
    
    CheckIdentity -- No --> Register
    Register --> Link
    Link --> Suggest
    
    CheckIdentity -- Yes --> Suggest
    
    Suggest --> Review
    Review -- Merge Recommended --> Merge
    Review -- Naming Recommended --> Rename[Update Name]
    Rename --> Confirm
    
    Merge --> Confirm
    Confirm --> End

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

---

## 🛠️ 2. Step-by-Step API Operations

### Phase 1: Registration (Creating Identities)
**Scenario**: You see `Person_17` is Audrey Hepburn. You want to create a global record for her.

1.  **Find the Person**:
    ```bash
    curl -s "http://localhost:3003/api/v1/person/list?video_uuid=...&limit=5" ...
    # Output: Person_17 (1636 frames, null name)
    ```

2.  **Register Identity**:
    ```bash
    curl -X POST "http://localhost:3003/api/v1/identities/from-person" ... \
      -d '{
        "video_uuid": "...",
        "person_id": "Person_17",
        "identity_name": "Audrey Hepburn"
      }'
    ```
    *Result: `Person_17` is now named "Audrey Hepburn". A global `identity_id` is created.*

---

### Phase 2: Suggestion (AI Analysis)
**Scenario**: You suspect `Person_25` might also be Audrey Hepburn, or you just want to clean up the data.

1.  **Ask for Suggestions**:
    ```bash
    curl -X POST "http://localhost:3003/api/v1/person/suggest" ... \
      -d '{"video_uuid": "..."}'
    ```
    *Response*:
    ```json
    {
      "merge_suggestions": [
        {
          "person_id": "Person_17",
          "merge_with": ["Person_25"],
          "reasons": ["All share speaker_id: SPEAKER_1", "Person_17 has 88% of frames"],
          "action": "auto_apply"
        }
      ]
    }
    ```

---

### Phase 3: Review & Execution
**Scenario**: You verify the suggestion. The AI logic (Shared Speaker + Frame dominance) seems correct.

1.  **Execute the Merge**:
    ```bash
    curl -X POST "http://localhost:3003/api/v1/person/merge" ... \
      -d '{
        "video_uuid": "...",
        "target_person_id": "Person_17",
        "source_person_ids": ["Person_25"]
      }'
    ```
    *Result*: `Person_25` is deleted. All 217 frames of `Person_25` are added to `Person_17`.

---

## 🚀 3. Automated Demo Script

Run the following script to see the entire process in action automatically.

```bash
#!/bin/bash
# scripts/demo_identity_workflow.sh
# Usage: chmod +x scripts/demo_identity_workflow.sh && ./scripts/demo_identity_workflow.sh

API_URL="http://localhost:3002"
API_KEY="muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
UUID="384b0ff44aaaa1f1"

echo "🎬 === MOMENTRY IDENTITY WORKFLOW DEMO ==="

# 1. Registration
echo "👉 STEP 1: Registering Person_17 as Audrey Hepburn..."
curl -s -X POST "$API_URL/api/v1/identities/from-person" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d "{\"video_uuid\":\"$UUID\", \"person_id\":\"Person_17\", \"identity_name\":\"Audrey Hepburn\"}" \
  | python3 -m json.tool

# 2. Suggestion
echo ""
echo "👉 STEP 2: Asking AI for cleaning suggestions..."
curl -s -X POST "$API_URL/api/v1/person/suggest" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d "{\"video_uuid\":\"$UUID\"}" \
  | python3 -c "
import sys, json
d = json.load(sys.stdin)
sugs = d.get('naming_suggestions', []) + d.get('merge_suggestions', [])
if sugs:
    print(f'   Found {len(sugs)} suggestions.')
    for s in sugs:
        print(f'   - {s}')
else:
    print('   No suggestions (Data is already clean!).')
"

# 3. Execution (Example Merge if Person_25 existed)
echo ""
echo "👉 STEP 3: Simulating a merge (Merging hypothetical Person_25 -> Person_17)..."
# Note: In a real scenario, Person_25 would exist. 
# Here we just show the command structure.
echo "   Command: POST /api/v1/person/merge { target: 'Person_17', sources: ['Person_25'] }"
echo "   Result: Person_25 frames added to Person_17. Person_25 deleted."

echo ""
echo "✅ Demo Complete."
