From 644516769c36053a92c5ea6cc94e2380554003f4 Mon Sep 17 00:00:00 2001 From: Accusys Date: Tue, 21 Jul 2026 03:22:09 +0800 Subject: [PATCH] docs: update TKG, profile, identity module docs with trace management and external_id fix - 15_tkg.md: external_id format changed to trace_N, added trace management section (delete/restore/merge) - 18_profile.md: note external_id matching fix - 07_identity.md: note bind/unbind external_id fix - regenerated user docs (doc/) --- .../API_WORKSPACE/modules/07_identity.md | 1 + docs_v1.0/API_WORKSPACE/modules/15_tkg.md | 101 +++++++++++++++++- docs_v1.0/API_WORKSPACE/modules/18_profile.md | 1 + docs_v1.0/doc/05_process.html | 43 +++++--- docs_v1.0/doc/07_identity.html | 3 +- docs_v1.0/doc/08_identity_agent.html | 91 +++++++++++++++- docs_v1.0/doc/10_pipeline.html | 26 +++-- 7 files changed, 237 insertions(+), 29 deletions(-) diff --git a/docs_v1.0/API_WORKSPACE/modules/07_identity.md b/docs_v1.0/API_WORKSPACE/modules/07_identity.md index 188946e..0879ce5 100644 --- a/docs_v1.0/API_WORKSPACE/modules/07_identity.md +++ b/docs_v1.0/API_WORKSPACE/modules/07_identity.md @@ -1102,4 +1102,5 @@ PATCH /api/v1/identity/:identity_uuid This **replaces** the entire `aliases` array. To add to existing aliases, include all existing entries in the request. --- +*Updated: 2026-07-21 — Fixed bind/unbind TKG update to match both trace_N and face_track_N external_id formats* *Updated: 2026-06-20 — Added identity files, chunks, faces, status, and JSON endpoints* diff --git a/docs_v1.0/API_WORKSPACE/modules/15_tkg.md b/docs_v1.0/API_WORKSPACE/modules/15_tkg.md index ca22254..011613e 100644 --- a/docs_v1.0/API_WORKSPACE/modules/15_tkg.md +++ b/docs_v1.0/API_WORKSPACE/modules/15_tkg.md @@ -14,7 +14,7 @@ TKG is a time-aligned knowledge graph built from multi-processor outputs (face, | Node Type | External ID Format | Description | Key Properties | |-----------|-------------------|-------------|----------------| -| `face_track` | `face_track_{trace_id}` | A tracked face identity over time | `trace_id`, `frame_count`, `status`, `pending_identity_name`, `confidence`, `identity_uuid` | +| `face_track` | `trace_{trace_id}` | A tracked face identity over time | `trace_id`, `frame_count`, `status`, `avg_bbox`, `avg_yaw`, `avg_pitch`, `avg_roll`, `start_frame`, `end_frame`, `pose_count` | | `gaze_track` | `gaze_track_{id}` | Gaze direction over time | `direction` (frontal/left/right/up/down + diagonals) | | `lip_track` | `lip_track_{id}` | Lip movement synced with speech | `speaker_id`, `lip_area_range` | | `text_region` | `text_region_{id}` | Spoken text aligned to time | `speaker_id`, `text`, `start_time`, `end_time` | @@ -426,4 +426,101 @@ curl -s "$API/api/v1/file/$FILE_UUID/processor-counts" \ --- -*Updated: 2026-06-25 17:00:00* +### Trace Management + +Endpoints for managing face traces: list, delete, restore, and merge. + +#### `DELETE /api/v1/file/:file_uuid/trace/:trace_id` + +**Auth**: Required + +Soft-delete a face trace (default) or hard-delete with `{"hard_delete": true}`. + +Soft delete marks Qdrant points with `status: "deleted"` and TKG nodes with `status: "deleted"` in properties. Deleted traces are excluded from the traces list. + +Hard delete permanently removes Qdrant points and TKG nodes. + +**Request Body** (optional): + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `hard_delete` | boolean | `false` | Permanently delete instead of marking | + +**Example**: +```bash +# Soft delete +curl -X DELETE "$API/api/v1/file/$FILE_UUID/trace/8" \ + -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{}' + +# Hard delete +curl -X DELETE "$API/api/v1/file/$FILE_UUID/trace/8" \ + -H "X-API-Key: $KEY" -H "Content-Type: application/json" \ + -d '{"hard_delete": true}' +``` + +**Response**: +```json +{ + "success": true, + "file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5", + "trace_id": 8, + "hard_delete": false, + "qdrant_marked": true, + "tkg_nodes_marked": 1 +} +``` + +--- + +#### `POST /api/v1/file/:file_uuid/trace/:trace_id/restore` + +**Auth**: Required + +Undo a soft-deleted trace. Clears `status: "deleted"` from Qdrant points and TKG node properties. + +**Example**: +```bash +curl -X POST "$API/api/v1/file/$FILE_UUID/trace/8/restore" \ + -H "X-API-Key: $KEY" +``` + +**Response**: +```json +{ + "success": true, + "file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5", + "trace_id": 8, + "qdrant_restored": true, + "tkg_nodes_restored": 1 +} +``` + +--- + +#### `POST /api/v1/file/:file_uuid/trace/:source_trace_id/merge/:target_trace_id` + +**Auth**: Required + +Merge all face points from source trace into target trace. Updates Qdrant `trace_id` and deletes source TKG node. + +**Example**: +```bash +curl -X POST "$API/api/v1/file/$FILE_UUID/trace/16/merge/3" \ + -H "X-API-Key: $KEY" +``` + +**Response**: +```json +{ + "success": true, + "file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5", + "source_trace_id": 16, + "target_trace_id": 3, + "points_moved": 58, + "tkg_nodes_deleted": 1 +} +``` + +--- + +*Updated: 2026-07-21 01:00:00* diff --git a/docs_v1.0/API_WORKSPACE/modules/18_profile.md b/docs_v1.0/API_WORKSPACE/modules/18_profile.md index b07a8ab..b9c594b 100644 --- a/docs_v1.0/API_WORKSPACE/modules/18_profile.md +++ b/docs_v1.0/API_WORKSPACE/modules/18_profile.md @@ -264,4 +264,5 @@ curl -s -X PUT "$API/api/v1/file-profile" \ | `aliases` | `properties->'aliases'` | Multi-language name aliases | --- +*Updated: 2026-07-21 — Fixed external_id matching (trace_N + face_track_N formats), fixed parameter ordering in UPDATE query* *Updated: 2026-07-18 — New profile module: trace-profile (GET, PUT, PUT group) and file-profile (GET, PUT)* diff --git a/docs_v1.0/doc/05_process.html b/docs_v1.0/doc/05_process.html index 17120e8..f5205b6 100644 --- a/docs_v1.0/doc/05_process.html +++ b/docs_v1.0/doc/05_process.html @@ -310,34 +310,45 @@ curl -s -X 6 face — -Face detection & embedding +Face detection & embedding (8Hz sampling) 7 -pose -— -Pose estimation +face_trace +face +Face tracking (IoU + embedding, assigns trace_id) 8 -visual_chunk -yolo -Visual scene chunks +pose +face_trace +Pose expansion from face traces, inherits trace_id 9 -story -asr, asrx, cut, yolo, face -Scene summaries (template) - - -10 -5w1h -story -5W1H analysis (Gemma4 LLM) +appearance +pose +Appearance expansion from pose traces, inherits trace_id +

Key Concepts: +- Face = Identity anchor (who is this person?) — requires high-quality embedding +- Pose = Tracking (where is this person?) — extends tracking when face is occluded +- Appearance = Tracking (what do they look like?) — extends tracking when pose is occluded

+

Trace ID Inheritance:

+
Face trace (identity anchor)
+    ↓ inherits trace_id
+Pose expansion (tracking continuity)
+    ↓ inherits trace_id
+Appearance expansion (tracking continuity)
+
+ +

Frame Count Relationship:

+
face frames ≤ pose frames ≤ appearance frames
+
+ +

(Each level expands outward from the previous level's traces)

All processors except story and 5w1h run concurrently when their dependencies are met. Story and 5W1H run sequentially after their prerequisites.

Example

curl -s -X POST "$API/api/v1/progress/$FILE_UUID" -H "X-API-Key: $KEY" | jq '{overall_progress, processors: [.processors[] | {name, status}]}'
diff --git a/docs_v1.0/doc/07_identity.html b/docs_v1.0/doc/07_identity.html
index 07e6ab6..d8ec1ab 100644
--- a/docs_v1.0/doc/07_identity.html
+++ b/docs_v1.0/doc/07_identity.html
@@ -1738,7 +1738,8 @@ curl -s -X 
 
 
This replaces the entire aliases array. To add to existing aliases, include all existing entries in the request.

 

-
Updated: 2026-06-20 — Added identity files, chunks, faces, status, and JSON endpoints

+
Updated: 2026-07-21 — Fixed bind/unbind TKG update to match both trace_N and face_track_N external_id formats
+Updated: 2026-06-20 — Added identity files, chunks, faces, status, and JSON endpoints
\ No newline at end of file diff --git a/docs_v1.0/doc/08_identity_agent.html b/docs_v1.0/doc/08_identity_agent.html index bab69cb..706f5b5 100644 --- a/docs_v1.0/doc/08_identity_agent.html +++ b/docs_v1.0/doc/08_identity_agent.html @@ -100,7 +100,96 @@ a { color: #0066cc; }
-

Updated: 2026-05-19 12:49:24

+

POST /api/v1/agents/identity/confirm

+

Auth: Required +Scope: file-level

+

Confirm identity binding for a trace. This marks the trace as confirmed in TKG, updates face_detections, adds to _seeds, and optionally triggers Round 2 propagation.

+

Request Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeRequiredDescription
file_uuidstringYesVideo file UUID
trace_idintegerYesFace trace ID to confirm
identity_idintegerYesIdentity internal ID
identity_uuidstringYesIdentity UUID
namestringYesIdentity name
propagatebooleanNoAuto-trigger Round 2 matching (default: true)
+

Example

+
curl -s -X POST "$API/api/v1/agents/identity/confirm" \
+  -H "Authorization: Bearer $JWT" \
+  -H "Content-Type: application/json" \
+  -d '{"file_uuid": "'"$FILE_UUID"'", "trace_id": 10, "identity_id": 42, "identity_uuid": "'"$IDENTITY_UUID"'", "name": "Cary Grant", "propagate": false}'
+
+ +

Response (200)

+
{
+  "success": true,
+  "file_uuid": "384b0ff44aaaa1f1",
+  "trace_id": 10,
+  "identity_uuid": "a9a90105...",
+  "name": "Cary Grant",
+  "steps": {
+    "tkg_updated": true,
+    "qdrant_updated": 150,
+    "pg_updated": 150,
+    "seed_added": true
+  },
+  "propagation": {
+    "matched": 5,
+    "message": "Propagation completed"
+  }
+}
+
+ +

Side Effects

+
    +
  1. TKG face_track node status → 'confirmed'
    2. +
  2. Qdrant _faces: identity_uuid added to payload
    3. +
  3. PG face_detections: identity_id set
    4. +
  4. Trace centroid added to _seeds (source='propagation')
    5. +
  5. Round 2 matching triggered (if propagate=true)
    6. +
+
+

Updated: 2026-06-26 00:30:00

\ No newline at end of file diff --git a/docs_v1.0/doc/10_pipeline.html b/docs_v1.0/doc/10_pipeline.html index 493e2c1..a1f7f6f 100644 --- a/docs_v1.0/doc/10_pipeline.html +++ b/docs_v1.0/doc/10_pipeline.html @@ -141,6 +141,12 @@ a { color: #0066cc; } chunk table has rows with chunk_type = 'sentence' +1.1 +Rule 1 OCR Chunks +OCR done +OCR pre_chunks grouped into sentence chunks + + 2 Auto-Vectorize Rule 1 done @@ -252,15 +258,17 @@ a { color: #0066cc; } 
{
   "file_uuid": "bd80fec9c42afb0307eb28f22c64c76a",
   "steps": [
-    { "name": "rule1_sentence", "status": "pending", "detail": "0 sentence chunks" },
-    { "name": "auto_vectorize",  "status": "pending", "detail": "0 embedded" },
-    { "name": "rule3_scene",     "status": "pending", "detail": "0 scene chunks" },
-    { "name": "face_trace",      "status": "pending", "detail": "0 traces" },
-    { "name": "trace_chunks",    "status": "pending", "detail": "0 trace chunks" },
-    { "name": "tkg",             "status": "pending", "detail": "0 nodes, 0 edges" },
-    { "name": "identity_match",  "status": "pending", "detail": "0 identities" },
-    { "name": "scene_metadata",  "status": "pending", "detail": null },
-    { "name": "5w1h",            "status": "pending", "detail": "0 scenes with 5W1H" }
+    { "name": "rule1_sentence",   "status": "done",    "detail": "35 sentence chunks" },
+    { "name": "rule1_ocr",        "status": "done",    "detail": "30 OCR frames" },
+    { "name": "rule1_ocr_chunks", "status": "done",    "detail": "3 OCR-only chunks" },
+    { "name": "auto_vectorize",   "status": "pending", "detail": "0 embedded" },
+    { "name": "rule3_scene",      "status": "pending", "detail": "0 scene chunks" },
+    { "name": "face_trace",       "status": "pending", "detail": "0 traces" },
+    { "name": "trace_chunks",     "status": "pending", "detail": "0 trace chunks" },
+    { "name": "tkg",              "status": "pending", "detail": "0 nodes, 0 edges" },
+    { "name": "identity_match",   "status": "pending", "detail": "0 identities" },
+    { "name": "scene_metadata",   "status": "pending", "detail": null },
+    { "name": "5w1h",             "status": "pending", "detail": "0 scenes with 5W1H" }
   ]
 }