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

feat: add source prefix to search results

Browse Source 
- Add [OCR], [ASRX], [ASRX+OCR] prefix to text_content
- Add content field to SemanticSearchResult struct
- Update SQL queries to include content field
- Helps users distinguish the source of search results
This commit is contained in:
Accusys
2026-07-19 14:06:06 +08:00
parent 5e83ee7dac
commit 87aa7e0c40
10 changed files with 3947 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs_v1.0/API_WORKSPACE/modules/18_profile.md
+267
View File
@@ -0,0 +1,267 @@
<!-- module: profile -->
<!-- description: Trace profile and file profile management — read/update face trace names, key frames, aliases, and file paths -->
<!-- depends: 01_auth, 07_identity, 15_tkg -->
## Profile Management
Endpoints for managing trace profiles (face track metadata stored in TKG) and file profiles (video metadata stored in PostgreSQL).
### `GET /api/v1/trace-profile`
**Auth**: Required
**Scope**: file-level
Read a single face trace's profile including name, key frame, key face, and multi-language aliases.
#### Request Parameters
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file_uuid` | string | Yes | File UUID |
| `trace_id` | integer | Yes | Trace ID (numeric) |
#### Example
```bash
curl -s "$API/api/v1/trace-profile?file_uuid=$FILE_UUID&trace_id=7" \
-H "X-API-Key: $KEY"
```
#### Response (200)
```json
{
"file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5",
"trace_id": 7,
"name": "John Doe",
"key_frame": 640,
"key_face": "face_12345",
"aliases": {
"en": "John Doe",
"zh": "約翰"
},
"properties": {
"status": "bound",
"avg_bbox": {"x": 899, "y": 212, "width": 342, "height": 342},
"start_frame": 624,
"end_frame": 669,
"frame_count": 5
}
}
```
| Field | Type | Description |
|-------|------|-------------|
| `file_uuid` | string | File UUID |
| `trace_id` | integer | Trace ID |
| `name` | string | Display name (from `tkg_nodes.label`) |
| `key_frame` | integer | Representative frame number, or null |
| `key_face` | string | Representative face ID, or null |
| `aliases` | object | Multi-language name aliases |
| `properties` | object | Full TKG node properties (bbox, frames, etc.) |
#### Error Responses
| HTTP | When |
|------|------|
| `404` | Trace not found |
| `401` | Missing or invalid API key |
---
### `PUT /api/v1/trace-profile`
**Auth**: Required
**Scope**: file-level
Update a single face trace's profile fields. Only provided fields are updated; others remain unchanged.
#### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file_uuid` | string | Yes | File UUID |
| `trace_id` | integer | Yes | Trace ID to update |
| `name` | string | No | New display name |
| `key_frame` | integer | No | Representative frame number |
| `key_face` | string | No | Representative face ID |
| `aliases` | object | No | Multi-language aliases `{"en": "...", "zh": "..."}` |
| `properties` | object | No | Additional properties to merge into existing JSONB |
#### Example
```bash
curl -s -X PUT "$API/api/v1/trace-profile" \
-H "X-API-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{
"file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5",
"trace_id": 7,
"name": "John Doe",
"key_frame": 640,
"key_face": "face_12345",
"aliases": {"en": "John Doe", "zh": "約翰"}
}'
```
#### Response (200)
```json
{
"success": true,
"message": "Trace profile updated",
"file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5",
"trace_id": 7
}
```
---
### `PUT /api/v1/trace-profile/group`
**Auth**: Required
**Scope**: file-level
Batch update the `name` (label) for multiple traces in a face group. Used when renaming a group.
#### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file_uuid` | string | Yes | File UUID |
| `trace_ids` | integer[] | Yes | List of trace IDs to update |
| `name` | string | Yes | New group name for all traces |
#### Example
```bash
curl -s -X PUT "$API/api/v1/trace-profile/group" \
-H "X-API-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{
"file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5",
"trace_ids": [7, 2, 13],
"name": "Group A"
}'
```
#### Response (200)
```json
{
"success": true,
"message": "Updated 3 traces in group",
"file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5",
"updated_count": 3
}
```
---
### `GET /api/v1/file-profile`
**Auth**: Required
**Scope**: file-level
Read a file's metadata including path, name, status, and technical details.
#### Request Parameters
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file_uuid` | string | Yes | File UUID |
#### Example
```bash
curl -s "$API/api/v1/file-profile?file_uuid=$FILE_UUID" \
-H "X-API-Key: $KEY"
```
#### Response (200)
```json
{
"file_uuid": "49884ce1c341953d1ad7bf67a77c30cc",
"file_name": "Dedicatoria.mp4",
"file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/Dedicatoria.mp4",
"status": "completed",
"duration": 93.33,
"width": 1280,
"height": 720,
"fps": 30.0,
"total_frames": 0
}
```
| Field | Type | Description |
|-------|------|-------------|
| `file_uuid` | string | File UUID |
| `file_name` | string | File name |
| `file_path` | string | Full filesystem path |
| `status` | string | `pending`, `processing`, `completed`, `failed` |
| `duration` | float | Duration in seconds |
| `width` | integer | Video width in pixels |
| `height` | integer | Video height in pixels |
| `fps` | float | Frames per second |
| `total_frames` | integer | Total frame count |
---
### `PUT /api/v1/file-profile`
**Auth**: Required
**Scope**: file-level
Update file metadata, typically used when a file is moved to a new location.
#### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file_uuid` | string | Yes | File UUID |
| `file_path` | string | No | New filesystem path |
| `file_name` | string | No | New file name |
#### Example
```bash
curl -s -X PUT "$API/api/v1/file-profile" \
-H "X-API-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{
"file_uuid": "49884ce1c341953d1ad7bf67a77c30cc",
"file_path": "/new/location/Dedicatoria.mp4"
}'
```
#### Response (200)
```json
{
"success": true,
"message": "File profile updated",
"file_uuid": "49884ce1c341953d1ad7bf67a77c30cc"
}
```
---
## Data Storage
| Profile Type | Storage | Table |
|-------------|---------|-------|
| **trace_profile** | PostgreSQL (TKG) | `tkg_nodes` where `node_type='face_track'` |
| **file_profile** | PostgreSQL | `videos` |
### Trace Profile Fields
| Field | TKG Column | Description |
|-------|-----------|-------------|
| `name` | `label` | Display name for the trace |
| `key_frame` | `properties->'key_frame'` | Representative frame number |
| `key_face` | `properties->'key_face'` | Representative face ID |
| `aliases` | `properties->'aliases'` | Multi-language name aliases |
---
*Updated: 2026-07-18 — New profile module: trace-profile (GET, PUT, PUT group) and file-profile (GET, PUT)*