warren/momentry_core
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

cleanup: remove dead code and duplicate docs

Browse Source 
- Remove session-ses_2f27.md (161KB raw session log)
- Remove 49 ROOT_* duplicate files across REFERENCE/
- Remove 14 duplicate files between REFERENCE/ root and history/
- Remove asr_legacy.rs (dead code, replaced by asr.rs)
- Remove src/core/worker/ (duplicate JobWorker)
- Remove src/core/layers/ (empty directory)
- Remove 4 .bak files in src/
- Remove 7 dead private methods in worker/processor.rs
- Remove backup directory from git tracking
This commit is contained in:
Warren
2026-05-04 01:31:21 +08:00
parent ee81e343ce
commit e75c4d6f07
3270 changed files with 35190 additions and 53367 deletions
Download Patch File Download Diff File Expand all files Collapse all files

811
docs_v1.0/IDENTITY_API_SPEC.md
View File

@@ -1,811 +0,0 @@
# Identity API Specification
> Version: V4.0 | Date: 2026-04-28
> Architecture: Two-layer (Face → Identity)
> Base URL: `http://localhost:3003/api/v1`
---
## Overview
| Category | Count | Description |
|----------|-------|-------------|
| **List API** | 6 | One-to-many queries |
| **Candidates API** | 2 | Unregistered face candidates |
| **Suggest API** | 2 | AI clustering suggestions |
| **Detail API** | 2 | Single item detail |
| **Register/Bind API** | 3 | Identity management operations |
| **Total** | **15** | Core endpoints |
---
## Terminology
| Term | Type | Description |
|------|------|-------------|
| **file_uuid** | UUID | Video file identifier |
| **identity_uuid** | UUID | Global identity identifier |
| **face_id** | string | Single face detection |
| **trace_id** | int | Face tracking ID |
| **chunk_id** | string | Sentence chunk ID |
---
## Pagination Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | int | 1 | Page number (>=1) |
| `page_size` | int | 15 | Items per page (1-100) |
| `limit` | int | null | Total items limit |
| `search` | string | null | Search query |
| `sort` | string | created_at | Sort field |
| `order` | string | DESC | Sort direction (ASC/DESC) |
---
## Response Format
### List API Response
```json
{
"success": true,
"data": {
"[items]": [...],
"pagination": {
"page": 1,
"page_size": 15,
"total": 100,
"total_pages": 7,
"limit": null
}
}
}
```
### Detail API Response
```json
{
"success": true,
"data": {
"[item]": {...}
}
}
```
### Error Response
```json
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Identity not found",
"details": {}
}
}
```
---
## 1. List API (One-to-Many)
---
### 1.1 GET /api/v1/files
List all files.
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
| `limit` | int | No | null |
| `search` | string | No | null |
| `status` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/files?page=1&page_size=15" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"files": [
{
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"file_name": "Charade_1963.mp4",
"duration": 6879.33,
"status": "completed",
"total_identities": 5,
"total_faces": 800,
"created_at": "2026-04-28T10:00:00Z"
}
],
"pagination": {
"page": 1,
"page_size": 15,
"total": 100,
"total_pages": 7
}
}
}
```
---
### 1.2 GET /api/v1/identities
List all identities.
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
| `limit` | int | No | null |
| `search` | string | No | null |
| `source` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/identities?page=1&page_size=15" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"identities": [
{
"identity_uuid": "a9a90105-6d6b-...",
"name": "Audrey Hepburn",
"source": "manual",
"total_files": 3,
"total_faces": 1500,
"reference_vectors": {
"total": 4,
"angles": ["frontal", "profile_right"]
},
"created_at": "2026-04-28T10:00:00Z"
}
],
"pagination": {
"page": 1,
"page_size": 15,
"total": 50,
"total_pages": 4
}
}
}
```
---
### 1.3 GET /api/v1/identities/:identity_uuid/files
List files where identity appears (N:N relationship).
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `identity_uuid` | UUID | Yes | - |
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
| `status` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../files" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"name": "Audrey Hepburn",
"files": [
{
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"file_name": "Charade_1963.mp4",
"face_count": 500,
"speaker_count": 10,
"first_appearance": 5.2,
"last_appearance": 180.5,
"confidence": 0.86
}
],
"total_files": 2
}
}
```
---
### 1.4 GET /api/v1/files/:file_uuid/identities
List identities in a file (N:N relationship).
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `file_uuid` | UUID | Yes | - |
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
| `status` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966/identities" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"file_name": "Charade_1963.mp4",
"identities": [
{
"identity_uuid": "a9a90105...",
"name": "Audrey Hepburn",
"face_count": 500,
"speaker_count": 10,
"confidence": 0.86
}
],
"total_identities": 5
}
}
```
---
### 1.5 GET /api/v1/identities/:identity_uuid/faces
List faces bound to an identity.
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `identity_uuid` | UUID | Yes | - |
| `page` | int | No | 1 |
| `page_size` | int | No | 100 |
| `limit` | int | No | 1000 |
| `pose_angle` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../faces?page_size=100" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"faces": [
{
"face_id": "face_100",
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"frame": 100,
"timestamp": 5.2,
"pose_angle": "frontal",
"confidence": 0.92,
"trace_id": 2
}
],
"total_faces": 1500,
"pose_distribution": {
"frontal": 400,
"profile_right": 300
}
}
}
```
---
### 1.6 GET /api/v1/identities/:identity_uuid/chunks
List chunks bound to an identity.
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `identity_uuid` | UUID | Yes | - |
| `page` | int | No | 1 |
| `page_size` | int | No | 50 |
| `limit` | int | No | 500 |
| `speaker_id` | string | No | null |
**Request**:
```bash
curl "http://localhost:3003/api/v1/identities/a9a90105.../chunks" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"chunks": [
{
"chunk_id": "chunk_1",
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"text": "Hello, how are you?",
"start_time": 5.2,
"end_time": 8.5,
"speaker_id": "SPEAKER_0"
}
],
"total_chunks": 30,
"speaker_ids": ["SPEAKER_0"],
"total_duration": 45.5
}
}
```
---
## 2. Candidates API (Unregistered)
---
### 2.1 GET /api/v1/faces/candidates
List unregistered faces (identity_id = NULL).
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `file_uuid` | UUID | No | null |
| `min_confidence` | float | No | 0.5 |
| `pose_angle` | string | No | null |
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
| `limit` | int | No | 100 |
**Request**:
```bash
curl "http://localhost:3003/api/v1/faces/candidates?min_confidence=0.8&pose_angle=frontal" \
-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,
"embedding_quality": 0.88
}
],
"statistics": {
"total_candidates": 78,
"pose_distribution": {
"frontal": 20,
"profile_right": 30
},
"avg_confidence": 0.85
},
"pagination": {
"page": 1,
"page_size": 15,
"total": 78,
"total_pages": 6
}
}
}
```
---
### 2.2 GET /api/v1/files/:file_uuid/faces/candidates
List unregistered faces in a specific file.
**Parameters**:
| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `file_uuid` | UUID | Yes | - |
| `min_confidence` | float | No | 0.5 |
| `page` | int | No | 1 |
| `page_size` | int | No | 15 |
**Request**:
```bash
curl "http://localhost:3003/api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966/faces/candidates" \
-H "X-API-Key: YOUR_KEY"
```
---
## 3. Suggest API (AI Agent)
---
### 3.1 POST /api/v1/agents/suggest/clustering
AI clustering suggestions for unregistered faces.
**Request Body**:
```json
{
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"min_confidence": 0.8,
"pose_angles": ["frontal"],
"clustering_threshold": 0.85,
"max_suggestions": 5
}
```
**Request**:
```bash
curl -X POST "http://localhost:3003/api/v1/agents/suggest/clustering" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{"min_confidence": 0.8, "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,
"trace_ids": [2, 3]
},
"reason": "High confidence frontal faces from same trace",
"action": "register"
}
],
"analysis_summary": {
"total_candidates": 78,
"potential_clusters": 5,
"suggested_actions": {
"register": 3,
"bind": 2
}
}
}
}
```
---
### 3.2 POST /api/v1/agents/suggest/merge
AI merge suggestions for identities.
**Request Body**:
```json
{
"identity_uuids": ["a9a90105...", "b8b80206..."],
"threshold": 0.85
}
```
**Request**:
```bash
curl -X POST "http://localhost:3003/api/v1/agents/suggest/merge" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{"identity_uuids": ["a9a90105...", "b8b80206..."]}'
```
**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..."]
}
}
]
}
}
```
---
## 4. Detail API (One-to-One)
---
### 4.1 GET /api/v1/identities/:identity_uuid
Identity detail.
**Parameters**:
| Parameter | Type | Required |
|-----------|------|----------|
| `identity_uuid` | UUID | Yes |
**Request**:
```bash
curl "http://localhost:3003/api/v1/identities/a9a90105..." \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"name": "Audrey Hepburn",
"source": "manual",
"identity_type": "person",
"global_stats": {
"total_files": 3,
"total_faces": 1500,
"total_speaker_segments": 30
},
"reference_vectors": {
"total": 4,
"angles": ["frontal", "profile_right"],
"quality_avg": 0.875
},
"created_at": "2026-04-28T10:00:00Z"
}
}
```
---
### 4.2 GET /api/v1/files/:file_uuid
File detail.
**Parameters**:
| Parameter | Type | Required |
|-----------|------|----------|
| `file_uuid` | UUID | Yes |
**Request**:
```bash
curl "http://localhost:3003/api/v1/files/384b0ff44aaaa1f14cb2cd63b3fea966" \
-H "X-API-Key: YOUR_KEY"
```
**Response**:
```json
{
"success": true,
"data": {
"file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
"file_name": "Charade_1963.mp4",
"duration": 6879.33,
"status": "completed",
"identity_stats": {
"total_identities": 5,
"identities": [
{"identity_uuid": "a9a90105...", "name": "Audrey Hepburn", "face_count": 500}
]
}
}
}
```
---
## 5. Register/Bind API
---
### 5.1 POST /api/v1/identities/register
Register new identity from faces.
**Request Body**:
```json
{
"face_ids": ["face_100", "face_150", "face_200"],
"name": "Audrey Hepburn",
"source": "manual",
"auto_bind_chunks": true
}
```
**Request**:
```bash
curl -X POST "http://localhost:3003/api/v1/identities/register" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
"face_ids": ["face_100"],
"name": "Audrey Hepburn",
"auto_bind_chunks": true
}'
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105-...",
"name": "Audrey Hepburn",
"faces_bound": 3,
"chunks_bound": 10,
"speaker_ids": ["SPEAKER_0"],
"reference_vectors": {
"total": 3,
"angles": ["frontal"]
}
}
}
```
---
### 5.2 POST /api/v1/identities/:identity_uuid/bind
Bind additional faces to existing identity.
**Request Body**:
```json
{
"face_ids": ["face_300", "face_400"],
"auto_bind_chunks": true
}
```
**Request**:
```bash
curl -X POST "http://localhost:3003/api/v1/identities/a9a90105.../bind" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{"face_ids": ["face_300"]}'
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"faces_bound": 1,
"chunks_bound": 3
}
}
```
---
### 5.3 POST /api/v1/identities/:identity_uuid/unbind
Unbind faces from identity.
**Request Body**:
```json
{
"face_ids": ["face_400"]
}
```
**Request**:
```bash
curl -X POST "http://localhost:3003/api/v1/identities/a9a90105.../unbind" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{"face_ids": ["face_400"]}'
```
**Response**:
```json
{
"success": true,
"data": {
"identity_uuid": "a9a90105...",
"faces_unbound": 1
}
}
```
---
## 6. Error Codes
| Code | HTTP Status | Description |
|------|-------------|-------------|
| `NOT_FOUND` | 404 | Resource not found |
| `BAD_REQUEST` | 400 | Invalid request |
| `UNAUTHORIZED` | 401 | Invalid API key |
| `INTERNAL_ERROR` | 500 | Server error |
| `VALIDATION_ERROR` | 422 | Validation failed |
---
## 7. Authentication
All endpoints require API key in header:
```bash
-H "X-API-Key: YOUR_API_KEY"
```
---
## Version History
| Version | Date | Changes |
|---------|------|---------|
| V4.0 | 2026-04-28 | Two-layer architecture, 15 core endpoints |
| V3.x | 2026-04-10 | 33 endpoints (many deprecated) |
---
## Deprecated Endpoints (V3.x → V4.0)
| Endpoint | Status | Replacement |
|----------|--------|--------------|
| `/api/v1/person/list` | ❌ Removed | `/api/v1/faces/candidates` |
| `/api/v1/person/:id` | ❌ Removed | `/api/v1/identities/:uuid` |
| `/api/v1/person/merge` | ❌ Removed | `/api/v1/agents/suggest/merge` |
| `/api/v1/person/:id/split` | ❌ Removed | Manual face re-binding |
| `/api/v1/chunks/candidates` | ❌ Removed | Chunks auto-bind |
| **26 more person APIs** | ❌ Removed | See above replacements |