feat: Phase 2.6 edges migration to Qdrant (TKG-only architecture)
Phase 2.6.1: co_occurrence_edges migration - build_co_occurrence_edges_from_qdrant() - Qdrant embeddings → frame grouping → YOLO objects - Result: 6679 edges (vs 6701 PostgreSQL) Phase 2.6.2: face_face_edges migration - build_face_face_edges_from_qdrant() - Qdrant embeddings → frame grouping → face pairs - mutual_gaze detection preserved - Result: 6 edges (exact match) Phase 2.6.3: speaker_face_edges migration - build_speaker_face_edges_from_qdrant() - Qdrant embeddings → trace_id frame ranges - SPEAKS_AS edge creation Architecture: - All edges use Qdrant payload (no face_detections queries) - PostgreSQL fallback for empty Qdrant - Estimated 3.6x performance improvement Testing: - Playground (3003): ✓ All Phase 2.6 logs verified - Edge counts: ✓ Close match with PostgreSQL - Fallback: ✓ Working Docs: - docs_v1.0/DESIGN/TKG_PHASE2_6_EDGES_MIGRATION.md - docs_v1.0/M4_workspace/2026-06-21_phase2_6_test.md
This commit is contained in:
Accusys
@@ -1,5 +1,5 @@
|
||||
<!-- module: lookup -->
|
||||
<!-- description: File lookup by name and unregistration -->
|
||||
<!-- description: File listing, lookup by name, file detail, faces, identities, JSON download, unregistration -->
|
||||
<!-- depends: 01_auth, 03_register -->
|
||||
|
||||
## File Lookup
|
||||
@@ -60,6 +60,285 @@ curl -s "$API/api/v1/files/lookup?file_name=charade" \
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## File Listing
|
||||
|
||||
### `GET /api/v1/files`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
List all registered files with pagination. Optionally filter by status or fetch a specific file by UUID.
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `page` | integer | No | 1 | Page number |
|
||||
| `page_size` | integer | No | 20 | Items per page |
|
||||
| `status` | string | No | — | Filter by status: `registered`, `processing`, `completed`, `failed`, `indexed`, `checked_out` |
|
||||
| `file_uuid` | string | No | — | Fetch a specific file (returns as single-item list) |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# List all files (paginated)
|
||||
curl -s "$API/api/v1/files?page=1&page_size=10" \
|
||||
-H "X-API-Key: $KEY"
|
||||
|
||||
# Filter by status
|
||||
curl -s "$API/api/v1/files?status=completed" \
|
||||
-H "X-API-Key: $KEY"
|
||||
|
||||
# Fetch specific file
|
||||
curl -s "$API/api/v1/files?file_uuid=$FILE_UUID" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"total": 42,
|
||||
"page": 1,
|
||||
"page_size": 10,
|
||||
"data": [
|
||||
{
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"file_name": "video.mp4",
|
||||
"file_path": "/path/to/video.mp4",
|
||||
"status": "completed"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `success` | boolean | Always true on 200 |
|
||||
| `total` | integer | Total file count |
|
||||
| `page` | integer | Current page |
|
||||
| `page_size` | integer | Items per page |
|
||||
| `data` | array | Array of file items |
|
||||
| `data[].file_uuid` | string | 32-char hex UUID |
|
||||
| `data[].file_name` | string | Registered file name |
|
||||
| `data[].file_path` | string | Full filesystem path |
|
||||
| `data[].status` | string | Processing status |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Get detailed info for a specific registered file including metadata, duration, FPS, and probe data.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/file/$FILE_UUID" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"file_name": "video.mp4",
|
||||
"file_path": "/path/to/video.mp4",
|
||||
"status": "completed",
|
||||
"duration": 120.5,
|
||||
"fps": 24.0,
|
||||
"metadata": {
|
||||
"format": {"duration": "120.5", "size": "794863677"},
|
||||
"streams": [{"codec_name": "h264", "width": 1920, "height": 1080}]
|
||||
},
|
||||
"created_at": "2026-05-16T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `success` | boolean | Always true on 200 |
|
||||
| `file_uuid` | string | 32-char hex UUID |
|
||||
| `file_name` | string | Registered file name |
|
||||
| `file_path` | string | Full filesystem path |
|
||||
| `status` | string | Processing status |
|
||||
| `duration` | float | Duration in seconds |
|
||||
| `fps` | float | Frames per second |
|
||||
| `metadata` | object | Full ffprobe metadata (probe.json) |
|
||||
| `created_at` | string | Registration timestamp (ISO 8601) |
|
||||
|
||||
#### Error Codes
|
||||
|
||||
| HTTP | When |
|
||||
|------|------|
|
||||
| `404` | File UUID not found |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/identities`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Get all identities present in a specific file with pagination.
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `page` | integer | No | 1 | Page number |
|
||||
| `page_size` | integer | No | 20 | Items per page |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/file/$FILE_UUID/identities?page=1&page_size=50" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"fps": 24.0,
|
||||
"total": 5,
|
||||
"page": 1,
|
||||
"page_size": 20,
|
||||
"data": [
|
||||
{
|
||||
"identity_id": 1,
|
||||
"identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
|
||||
"name": "Audrey Hepburn",
|
||||
"metadata": {"source": "tmdb", "tmdb_id": 1234},
|
||||
"face_count": 142,
|
||||
"speaker_count": 8,
|
||||
"start_frame": 100,
|
||||
"end_frame": 5000,
|
||||
"start_time": 4.17,
|
||||
"end_time": 208.33,
|
||||
"confidence": 0.87
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `data[].identity_id` | integer | Database identity ID |
|
||||
| `data[].identity_uuid` | string/null | Global identity UUID (null if unbound) |
|
||||
| `data[].name` | string | Identity name |
|
||||
| `data[].metadata` | object | Source metadata (TMDb, etc.) |
|
||||
| `data[].face_count` | integer/null | Number of face detections |
|
||||
| `data[].speaker_count` | integer/null | Number of speaker segments |
|
||||
| `data[].start_frame` | integer/null | First appearance frame |
|
||||
| `data[].end_frame` | integer/null | Last appearance frame |
|
||||
| `data[].start_time` | float/null | First appearance time (seconds) |
|
||||
| `data[].end_time` | float/null | Last appearance time (seconds) |
|
||||
| `data[].confidence` | float/null | Average detection confidence |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/faces`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
List all face detections in a specific file with pagination.
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `page` | integer | No | 1 | Page number |
|
||||
| `page_size` | integer | No | 50 | Items per page |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/file/$FILE_UUID/faces?page=1&page_size=100" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"total": 1420,
|
||||
"page": 1,
|
||||
"page_size": 50,
|
||||
"data": [
|
||||
{
|
||||
"face_id": "face_100",
|
||||
"frame_number": 1200,
|
||||
"timestamp": 50.0,
|
||||
"bbox": [100, 50, 300, 400],
|
||||
"confidence": 0.95,
|
||||
"identity_id": 1,
|
||||
"identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
|
||||
"trace_id": 2
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `data[].face_id` | string | Face detection ID |
|
||||
| `data[].frame_number` | integer | Frame number in video |
|
||||
| `data[].timestamp` | float | Timestamp in seconds |
|
||||
| `data[].bbox` | array | Bounding box `[x1, y1, x2, y2]` |
|
||||
| `data[].confidence` | float | Detection confidence |
|
||||
| `data[].identity_id` | integer/null | Bound identity ID (null if unbound) |
|
||||
| `data[].identity_uuid` | string/null | Bound identity UUID (null if unbound) |
|
||||
| `data[].trace_id` | integer/null | Face trace ID (null if not traced) |
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/file/:file_uuid/json/:processor`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Download raw JSON output for a specific processor.
|
||||
|
||||
#### Path Parameters
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `file_uuid` | string | Yes | File UUID |
|
||||
| `processor` | string | Yes | Processor name: `cut`, `asrx`, `yolo`, `ocr`, `face`, `pose`, `story`, etc. |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/file/$FILE_UUID/json/face" \
|
||||
-H "X-API-Key: $KEY" | jq '.frames | length'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
Returns the raw JSON output of the specified processor. Structure varies by processor type.
|
||||
|
||||
#### Error Codes
|
||||
|
||||
| HTTP | When |
|
||||
|------|------|
|
||||
| `404` | JSON file not found |
|
||||
| `500` | Failed to parse JSON |
|
||||
|
||||
---
|
||||
|
||||
## Unregister
|
||||
|
||||
### `POST /api/v1/unregister`
|
||||
@@ -138,4 +417,4 @@ curl -s -X POST "$API/api/v1/unregister" \
|
||||
| `401` | Missing or invalid API key |
|
||||
|
||||
---
|
||||
*Updated: 2026-05-19 12:49:24*
|
||||
*Updated: 2026-06-20 — Added file listing, file detail, file identities, file faces, and JSON download endpoints*
|
||||
|
||||
@@ -235,5 +235,174 @@ curl -s "$API/api/v1/jobs" -H "X-API-Key: $KEY" | jq '{count, jobs: [.jobs[] | {
|
||||
| `page` | integer | Current page number |
|
||||
| `page_size` | integer | Jobs per page |
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/processor-counts`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Get counts of processor JSON output files. See `15_tkg.md` for full documentation.
|
||||
|
||||
---
|
||||
*Updated: 2026-05-19 12:49:24*
|
||||
|
||||
## Pipeline Steps (Manual)
|
||||
|
||||
These endpoints execute individual pipeline steps. They are typically called by the worker automatically, but can be invoked manually for debugging or re-processing.
|
||||
|
||||
### `POST /api/v1/file/:file_uuid/store-asrx`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Store ASRX diarization results as chunk records in the database. Converts ASRX segments into searchable chunk entries.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/file/$FILE_UUID/store-asrx" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "ASRX chunks stored",
|
||||
"file_uuid": "3a6c1865..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/file/:file_uuid/rule1`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Execute Rule 1 pipeline step. Applies rule-based chunking to create structured chunk records from processor outputs.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/file/$FILE_UUID/rule1" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Rule 1 complete: 45 chunks",
|
||||
"file_uuid": "3a6c1865...",
|
||||
"chunks": 45
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `success` | boolean | Always true on 200 |
|
||||
| `message` | string | Human-readable completion message |
|
||||
| `file_uuid` | string | 32-char hex UUID |
|
||||
| `chunks` | integer | Number of chunks produced |
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/file/:file_uuid/vectorize`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Generate vector embeddings for all chunks of a file and store them in Qdrant for semantic search.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/file/$FILE_UUID/vectorize" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Vectorization complete",
|
||||
"file_uuid": "3a6c1865..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/file/:file_uuid/phase1`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Execute Phase 1 of the post-processing pipeline. Combines store-asrx, rule1, and vectorize into a single step.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/file/$FILE_UUID/phase1" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Phase 1 complete",
|
||||
"file_uuid": "3a6c1865..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/file/:file_uuid/complete`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Mark a video as fully processed. Updates the video status to `completed` and finalizes all pipeline state.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/file/$FILE_UUID/complete" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Video marked as completed",
|
||||
"file_uuid": "3a6c1865..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pipeline Step Order
|
||||
|
||||
```
|
||||
process (trigger)
|
||||
│
|
||||
├─→ cut, yolo, ocr, face, pose, asrx (parallel processors)
|
||||
│
|
||||
├─→ store-asrx (store diarization as chunks)
|
||||
│
|
||||
├─→ rule1 (rule-based chunking)
|
||||
│
|
||||
├─→ vectorize (embed chunks to Qdrant)
|
||||
│
|
||||
└─→ complete (mark done)
|
||||
```
|
||||
|
||||
Phase 1 (`/phase1`) combines store-asrx + rule1 + vectorize into one call.
|
||||
|
||||
---
|
||||
*Updated: 2026-06-20 12:00:00*
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- module: search -->
|
||||
<!-- description: Vector search, BM25, smart search, universal search, visual search -->
|
||||
<!-- description: Vector search, BM25, smart search, universal search, LLM reranked search, frame search -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
## Search APIs
|
||||
@@ -160,11 +160,137 @@ curl -s -X POST "$API/api/v1/search/universal" \
|
||||
**Auth**: Required
|
||||
**Scope**: global / file-level
|
||||
|
||||
Search face detection frames by identity name or trace ID.
|
||||
Search frames by YOLO objects, OCR text, face IDs, or pose detections. Filters frames based on visual content detected during processing.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `file_uuid` | string | No | — | Restrict to specific file |
|
||||
| `object_class` | string | No | — | Filter by YOLO object class (e.g., `person`, `car`, `dog`) |
|
||||
| `ocr_text` | string | No | — | Filter by OCR text content (ILIKE match) |
|
||||
| `face_id` | string | No | — | Filter by face detection ID |
|
||||
| `time_range` | [float, float] | No | — | Filter by time range `[start_secs, end_secs]` |
|
||||
| `limit` | integer | No | 100 | Max results |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Search for frames containing "person" objects
|
||||
curl -s -X POST "$API/api/v1/search/frames" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"file_uuid": "'"$FILE_UUID"'", "object_class": "person", "limit": 20}'
|
||||
|
||||
# Search for frames with specific OCR text
|
||||
curl -s -X POST "$API/api/v1/search/frames" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"file_uuid": "'"$FILE_UUID"'", "ocr_text": "hello", "time_range": [10.0, 30.0]}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"frames": [
|
||||
{
|
||||
"frame_number": 1200,
|
||||
"timestamp": 50.0,
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"objects": [{"class": "person", "confidence": 0.95, "bbox": [100, 50, 300, 400]}],
|
||||
"ocr_texts": ["Hello World"],
|
||||
"faces": [{"face_id": "face_42", "confidence": 0.88}],
|
||||
"pose_persons": [{"trace_id": 2, "bbox": [120, 60, 280, 380]}]
|
||||
}
|
||||
],
|
||||
"total": 15
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `frames` | array | Array of matching frame objects |
|
||||
| `frames[].frame_number` | integer | Frame number in video |
|
||||
| `frames[].timestamp` | float | Timestamp in seconds |
|
||||
| `frames[].file_uuid` | string | File UUID |
|
||||
| `frames[].objects` | array/null | YOLO detections in this frame |
|
||||
| `frames[].ocr_texts` | array/null | OCR text strings in this frame |
|
||||
| `frames[].faces` | array/null | Face detections in this frame |
|
||||
| `frames[].pose_persons` | array/null | Pose-detected persons in this frame |
|
||||
| `total` | integer | Total matching frame count |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/search/identity_text`
|
||||
### `POST /api/v1/search/llm-smart`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: global / file-level
|
||||
|
||||
Smart search with LLM re-ranking. First fetches candidate results via RRF (Reciprocal Rank Fusion) using the existing smart search, then uses an LLM (Gemma4 on port 8000) to re-rank candidates by relevance to the query.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `query` | string | Yes | — | Search text |
|
||||
| `file_uuid` | string | No | — | File UUID to search within |
|
||||
| `limit` | integer | No | 10 | Max results to return |
|
||||
|
||||
#### Pipeline
|
||||
|
||||
```
|
||||
1. smart_search → fetch N candidates (limit × 3, clamped 10-20)
|
||||
2. LLM rerank → re-order by relevance using Gemma4
|
||||
3. trim → return top `limit` results
|
||||
```
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/search/llm-smart" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"query": "two people having a conversation about business", "limit": 5}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "two people having a conversation about business",
|
||||
"results": [
|
||||
{
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"parent_id": 1234,
|
||||
"scene_order": 1234,
|
||||
"start_frame": 5000,
|
||||
"end_frame": 5200,
|
||||
"fps": 24.0,
|
||||
"start_time": 208.3,
|
||||
"end_time": 216.7,
|
||||
"summary": "[208s-217s, 9s] Two people discussing project timeline...",
|
||||
"similarity": 0.72
|
||||
}
|
||||
],
|
||||
"page": 1,
|
||||
"page_size": 5,
|
||||
"strategy": "llm_reranked"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `strategy` | string | Always `"llm_reranked"` for this endpoint |
|
||||
| `results` | array | Re-ranked search results (same format as smart search) |
|
||||
|
||||
#### Fallback
|
||||
|
||||
If LLM reranking fails (model unavailable, timeout), falls back to RRF order without error.
|
||||
|
||||
---
|
||||
|
||||
### Visual Search
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: global / file-level
|
||||
@@ -223,15 +349,15 @@ curl -s "$API/api/v1/search/identity_text?file_uuid=$FILE_UUID&q=love" -H "X-API
|
||||
|
||||
---
|
||||
|
||||
### Visual Search
|
||||
### Visual Search (Planned)
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| POST | `/api/v1/search/visual` | Search visual chunks |
|
||||
| POST | `/api/v1/search/visual/class` | Search by object class |
|
||||
| POST | `/api/v1/search/visual/density` | Search by object density |
|
||||
| POST | `/api/v1/search/visual/combination` | Search by object combination |
|
||||
| POST | `/api/v1/search/visual/stats` | Visual chunk statistics |
|
||||
| Method | Endpoint | Status | Description |
|
||||
|--------|----------|--------|-------------|
|
||||
| POST | `/api/v1/search/visual` | Not implemented | Search visual chunks |
|
||||
| POST | `/api/v1/search/visual/class` | Not implemented | Search by object class |
|
||||
| POST | `/api/v1/search/visual/density` | Not implemented | Search by object density |
|
||||
| POST | `/api/v1/search/visual/combination` | Not implemented | Search by object combination |
|
||||
| POST | `/api/v1/search/visual/stats` | Not implemented | Visual chunk statistics |
|
||||
|
||||
#### Embedding Model
|
||||
|
||||
@@ -243,4 +369,4 @@ curl -s "$API/api/v1/search/identity_text?file_uuid=$FILE_UUID&q=love" -H "X-API
|
||||
| **Storage** | pgvector (`chunk.embedding` column) |
|
||||
|
||||
---
|
||||
*Updated: 2026-05-27 — Added global search support for smart, universal, identity_text APIs*
|
||||
*Updated: 2026-06-20 — Added llm-smart search, completed frames search documentation, marked visual search as planned*
|
||||
|
||||
@@ -729,6 +729,200 @@ curl -s "$API/api/v1/identity/$IDENTITY_UUID/profile-image" \
|
||||
|
||||
---
|
||||
|
||||
## Identity Related Data
|
||||
|
||||
### `GET /api/v1/identity/:identity_uuid/files`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
List all files containing this identity.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identity/$IDENTITY_UUID/files" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
|
||||
"total": 3,
|
||||
"files": [
|
||||
{
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"file_name": "video1.mp4",
|
||||
"face_count": 142,
|
||||
"first_appearance": 4.17,
|
||||
"last_appearance": 208.33
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/identity/:identity_uuid/chunks`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
List all chunks associated with this identity (chunks where the identity's face appears).
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `page` | integer | No | 1 | Page number |
|
||||
| `page_size` | integer | No | 20 | Items per page |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identity/$IDENTITY_UUID/chunks?page=1&page_size=50" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
|
||||
"total": 45,
|
||||
"page": 1,
|
||||
"page_size": 20,
|
||||
"chunks": [
|
||||
{
|
||||
"chunk_id": "chunk_1",
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"start_time": 4.17,
|
||||
"end_time": 8.33,
|
||||
"text": "[4s-8s] Hello, how are you?",
|
||||
"chunk_type": "story_child"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/identity/:identity_uuid/faces`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
List all face detections for this identity.
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `page` | integer | No | 1 | Page number |
|
||||
| `page_size` | integer | No | 50 | Items per page |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identity/$IDENTITY_UUID/faces?page=1&page_size=100" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
|
||||
"total": 1420,
|
||||
"page": 1,
|
||||
"page_size": 50,
|
||||
"faces": [
|
||||
{
|
||||
"face_id": "face_100",
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"frame_number": 1200,
|
||||
"timestamp": 50.0,
|
||||
"bbox": [100, 50, 300, 400],
|
||||
"confidence": 0.95,
|
||||
"trace_id": 2
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/identity/:identity_uuid/status`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Get processing/status info for an identity.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identity/$IDENTITY_UUID/status" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
|
||||
"name": "Audrey Hepburn",
|
||||
"status": "confirmed",
|
||||
"face_count": 1420,
|
||||
"file_count": 3,
|
||||
"has_embedding": true,
|
||||
"has_profile_image": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/identity/:identity_uuid/json`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Get the raw identity JSON file (same format as identity.json on disk).
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identity/$IDENTITY_UUID/json" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
|
||||
"name": "Audrey Hepburn",
|
||||
"identity_type": "people",
|
||||
"source": "tmdb",
|
||||
"status": "confirmed",
|
||||
"tmdb_id": 1234,
|
||||
"tmdb_profile": "https://image.tmdb.org/...",
|
||||
"metadata": {},
|
||||
"file_bindings": [
|
||||
{"file_uuid": "d3f9ae8e...", "trace_ids": [0, 1, 2], "face_count": 142}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Alias System (BCP 47 Locale Tags)
|
||||
|
||||
Identity aliases support multilingual display names. Aliases are stored in `metadata.aliases` as an array of `{locale, name}` objects.
|
||||
@@ -786,4 +980,4 @@ 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-05-25 — Added `GET /api/v1/file/:file_uuid/faces` with 4 binding states, filters, strangers table split
|
||||
*Updated: 2026-06-20 — Added identity files, chunks, faces, status, and JSON endpoints*
|
||||
|
||||
@@ -427,4 +427,111 @@ Both endpoints support time range extraction, but serve different use cases:
|
||||
| **Frame number** | Zero-based (`frame=0` = first frame of video) |
|
||||
|
||||
---
|
||||
*Updated: 2026-05-19 12:49:24*
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/stranger/:stranger_id/representative-face`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Get the representative face for a stranger (unidentified face trace).
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/file/$FILE_UUID/stranger/1/representative-face" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"stranger_id": 1,
|
||||
"face_count": 85,
|
||||
"representative": {
|
||||
"frame_number": 5000,
|
||||
"timestamp_secs": 208.33,
|
||||
"bbox": {"x": 200, "y": 100, "width": 150, "height": 150},
|
||||
"confidence": 0.92,
|
||||
"quality_score": 20700,
|
||||
"blur_score": 8.5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/stranger/:stranger_id/thumbnail`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Extract the best face image for a stranger as JPEG (320×320).
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/file/$FILE_UUID/stranger/1/thumbnail" \
|
||||
-H "X-API-Key: $KEY" -o stranger_1_face.jpg
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
- **200**: `image/jpeg` binary data (320×320 cropped face)
|
||||
- **404**: File or stranger not found
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/chunk/:chunk_id/thumbnail`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Get thumbnail for a specific chunk. Extracts the representative frame for the chunk's time range.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/file/$FILE_UUID/chunk/chunk_1/thumbnail" \
|
||||
-H "X-API-Key: $KEY" -o chunk_1.jpg
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
- **200**: `image/jpeg` binary data
|
||||
- **404**: File or chunk not found
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/media-proxy`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
Proxy request to fetch media from external URLs. Useful for loading profile images or thumbnails from external services (TMDb, etc.) without exposing the external URL to the client.
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `url` | string | Yes | External URL to proxy |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/media-proxy?url=https://image.tmdb.org/t/p/w500/abc123.jpg" \
|
||||
-H "X-API-Key: $KEY" -o tmdb_profile.jpg
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
- **200**: Proxied media data (Content-Type from external source)
|
||||
- **400**: Missing or invalid URL parameter
|
||||
- **500**: External request failed
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
*Updated: 2026-06-20 — Added stranger endpoints, chunk thumbnail, and media proxy*
|
||||
|
||||
@@ -108,5 +108,94 @@ curl -s -X POST "$API/api/v1/resource/tmdb/check" \
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/v1/tmdb/fetch`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
Fetch TMDb data by filename, create identities with profile images and embeddings. Similar to prefetch+probe combined, but also downloads profile images and generates embeddings.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `filename` | string | Yes | Movie filename to search TMDb for |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/tmdb/fetch" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"filename": "charade.mp4"}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"movie_title": "Charade (1963)",
|
||||
"tmdb_id": 1234,
|
||||
"identities_created": 15,
|
||||
"profile_images_downloaded": 12
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
*Updated: 2026-05-19 12:49:24*
|
||||
|
||||
### `POST /api/v1/agents/tmdb/match/:file_uuid`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Match TMDb identities to face traces using Qdrant vector similarity. Compares face embeddings against TMDb identity embeddings to find the best matches.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/agents/tmdb/match/$FILE_UUID" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"matches": [
|
||||
{
|
||||
"trace_id": 0,
|
||||
"identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
|
||||
"identity_name": "Audrey Hepburn",
|
||||
"confidence": 0.92,
|
||||
"tmdb_id": 1234
|
||||
}
|
||||
],
|
||||
"total_matches": 5
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `matches[].trace_id` | integer | Face trace ID |
|
||||
| `matches[].identity_uuid` | string | Matched TMDb identity UUID |
|
||||
| `matches[].identity_name` | string | Identity display name |
|
||||
| `matches[].confidence` | float | Cosine similarity score (0.0–1.0) |
|
||||
| `matches[].tmdb_id` | integer | TMDb person ID |
|
||||
| `total_matches` | integer | Total successful matches |
|
||||
|
||||
---
|
||||
|
||||
### TMDb Auto-Match
|
||||
|
||||
When `MOMENTRY_TMDB_PROBE_ENABLED=true`, the worker automatically runs TMDb matching during the post-process phase:
|
||||
|
||||
1. **Register phase**: Searches TMDb by filename, creates identities with `tmdb_id`/`tmdb_profile`
|
||||
2. **Post-process phase**: Matches detected faces against TMDb identities via cosine similarity using Qdrant
|
||||
|
||||
No manual API call needed if auto-match is enabled.
|
||||
|
||||
---
|
||||
*Updated: 2026-06-20 — Added tmdb/fetch and tmdb/match endpoints*
|
||||
|
||||
47
docs_v1.0/doc_wasm/modules/101_CLI_Register.md
Normal file
47
docs_v1.0/doc_wasm/modules/101_CLI_Register.md
Normal file
@@ -0,0 +1,47 @@
|
||||
<!-- module: cli_register -->
|
||||
<!-- description: Register a video file into the system -->
|
||||
<!-- depends: none -->
|
||||
|
||||
# Register — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry register <PATH>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Register a video file into the Momentry system. This creates a database record for the video and generates its UUID.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `PATH` | string | Yes | Video file path or URL to register |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Register a local video file
|
||||
momentry register /path/to/video.mp4
|
||||
|
||||
# Register via URL
|
||||
momentry register https://example.com/video.mp4
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
**Note**: Register requires file system access and is typically run as a CLI command.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `process` — Process the registered video
|
||||
- `lookup` — Lookup UUID from path
|
||||
- `status` — Check registration status
|
||||
58
docs_v1.0/doc_wasm/modules/102_CLI_Process.md
Normal file
58
docs_v1.0/doc_wasm/modules/102_CLI_Process.md
Normal file
@@ -0,0 +1,58 @@
|
||||
<!-- module: cli_process -->
|
||||
<!-- description: Process video to generate all processor JSON files -->
|
||||
<!-- depends: cli_register -->
|
||||
|
||||
# Process — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry process <TARGET> [OPTIONS]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Process a registered video to generate processor output files (ASR, Cut, ASRX, YOLO, OCR, Face, Pose, Story, Caption).
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `TARGET` | string | Yes | UUID or path of the video to process |
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `-m, --modules` | string[] | all | Modules to process (comma separated: asr,cut,asrx,yolo,ocr,face,pose,story,caption) |
|
||||
| `--cloud` | string[] | none | Modules to process via cloud (comma separated) |
|
||||
| `--force` | bool | false | Force reprocess even if JSON exists |
|
||||
| `--resume` | bool | false | Resume from last checkpoint if interrupted |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Process all modules
|
||||
momentry process 384b0ff44aaaa1f1
|
||||
|
||||
# Process specific modules
|
||||
momentry process 384b0ff44aaaa1f1 --modules asr,cut,face
|
||||
|
||||
# Force reprocess
|
||||
momentry process 384b0ff44aaaa1f1 --force
|
||||
|
||||
# Resume interrupted processing
|
||||
momentry process 384b0ff44aaaa1f1 --resume
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
**Note**: Process requires file system access and processor execution.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `register` — Register video before processing
|
||||
- `chunk` — Generate chunks after processing
|
||||
- `status` — Check processing status
|
||||
44
docs_v1.0/doc_wasm/modules/103_CLI_Chunk.md
Normal file
44
docs_v1.0/doc_wasm/modules/103_CLI_Chunk.md
Normal file
@@ -0,0 +1,44 @@
|
||||
<!-- module: cli_chunk -->
|
||||
<!-- description: Generate chunks and store in database -->
|
||||
<!-- depends: cli_process -->
|
||||
|
||||
# Chunk — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry chunk <UUID>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Generate chunks from processed video data and store them in the database. Chunks are text segments used for RAG search.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `UUID` | string | Yes | File UUID of the processed video |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Generate chunks for a video
|
||||
momentry chunk 384b0ff44aaaa1f1
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
**Note**: Chunk requires database write access.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `process` — Process video before chunking
|
||||
- `vectorize` — Vectorize chunks for search
|
||||
- `query` — Query using chunks
|
||||
41
docs_v1.0/doc_wasm/modules/104_CLI_StoreAsrx.md
Normal file
41
docs_v1.0/doc_wasm/modules/104_CLI_StoreAsrx.md
Normal file
@@ -0,0 +1,41 @@
|
||||
<!-- module: cli_store_asrx -->
|
||||
<!-- description: Store ASRX chunks into pre_chunks table -->
|
||||
<!-- depends: cli_process -->
|
||||
|
||||
# Store-Asrx — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry store-asrx <UUID>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Store ASRX (speaker diarization) chunks into the pre_chunks table for further processing.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `UUID` | string | Yes | File UUID of the processed video |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Store ASRX chunks
|
||||
momentry store-asrx 384b0ff44aaaa1f1
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `process` — Process video with ASRX module
|
||||
- `chunk` — Generate final chunks
|
||||
41
docs_v1.0/doc_wasm/modules/105_CLI_Story.md
Normal file
41
docs_v1.0/doc_wasm/modules/105_CLI_Story.md
Normal file
@@ -0,0 +1,41 @@
|
||||
<!-- module: cli_story -->
|
||||
<!-- description: Generate story descriptions for cut scenes -->
|
||||
<!-- depends: cli_process -->
|
||||
|
||||
# Story — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry story <UUID>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Generate narrative story descriptions for cut scenes using LLM.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `UUID` | string | Yes | File UUID of the processed video |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Generate story for cut scenes
|
||||
momentry story 384b0ff44aaaa1f1
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `process` — Process video with cut module
|
||||
- `phase1` — Full release pipeline
|
||||
62
docs_v1.0/doc_wasm/modules/106_CLI_Detect.md
Normal file
62
docs_v1.0/doc_wasm/modules/106_CLI_Detect.md
Normal file
@@ -0,0 +1,62 @@
|
||||
<!-- module: cli_detect -->
|
||||
<!-- description: Detect objects in an image using CLIP or Qwen3-VL -->
|
||||
<!-- depends: none -->
|
||||
|
||||
# Detect — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry detect --image <PATH> --objects <LIST> [OPTIONS]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Detect specified objects in an image using CLIP (fast) or Qwen3-VL (accurate). Supports cascade mode for optimal results.
|
||||
|
||||
## Arguments
|
||||
|
||||
None (uses options).
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Type | Required | Default | Description |
|
||||
|--------|------|----------|---------|-------------|
|
||||
| `-i, --image` | string | Yes | — | Image file path |
|
||||
| `-o, --objects` | string[] | Yes | — | Objects to detect (comma separated) |
|
||||
| `--cascade` | bool | No | false | Use cascade mode (CLIP first, Qwen3-VL for high confidence) |
|
||||
| `--threshold` | f32 | No | 0.7 | CLIP confidence threshold for cascade |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Detect single object
|
||||
momentry detect --image photo.jpg --objects cat
|
||||
|
||||
# Detect multiple objects
|
||||
momentry detect --image photo.jpg --objects cat,dog,car
|
||||
|
||||
# Cascade mode with custom threshold
|
||||
momentry detect --image photo.jpg --objects person --cascade --threshold 0.8
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: `momentry detect '<json-args>'`
|
||||
|
||||
**JSON Args**:
|
||||
```json
|
||||
{
|
||||
"image": "/path/to/image.jpg",
|
||||
"objects": ["cat", "dog"],
|
||||
"cascade": false,
|
||||
"threshold": 0.7
|
||||
}
|
||||
```
|
||||
|
||||
**Returns**: JSON with detected objects and confidence scores.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `vision` — Vision LLM management
|
||||
- `process` — Process with YOLO module
|
||||
57
docs_v1.0/doc_wasm/modules/107_CLI_Vision.md
Normal file
57
docs_v1.0/doc_wasm/modules/107_CLI_Vision.md
Normal file
@@ -0,0 +1,57 @@
|
||||
<!-- module: cli_vision -->
|
||||
<!-- description: Vision LLM management subcommands -->
|
||||
<!-- depends: none -->
|
||||
|
||||
# Vision — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry vision <SUBCOMMAND>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Manage the Qwen3-VL vision LLM server for image analysis tasks.
|
||||
|
||||
## Subcommands
|
||||
|
||||
| Subcommand | Description |
|
||||
|------------|-------------|
|
||||
| `start` | Start Qwen3-VL server |
|
||||
| `stop` | Stop Qwen3-VL server |
|
||||
| `status` | Check Qwen3-VL server status |
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `SUBCOMMAND` | string | Yes | One of: start, stop, status |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Start vision server
|
||||
momentry vision start
|
||||
|
||||
# Check server status
|
||||
momentry vision status
|
||||
|
||||
# Stop server
|
||||
momentry vision stop
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
**Note**: Vision server management requires system access.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `detect` — Object detection using vision models
|
||||
- `process` — Video processing with vision modules
|
||||
47
docs_v1.0/doc_wasm/modules/108_CLI_Vectorize.md
Normal file
47
docs_v1.0/doc_wasm/modules/108_CLI_Vectorize.md
Normal file
@@ -0,0 +1,47 @@
|
||||
<!-- module: cli_vectorize -->
|
||||
<!-- description: Vectorize chunks for semantic search -->
|
||||
<!-- depends: cli_chunk -->
|
||||
|
||||
# Vectorize — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry vectorize <UUID>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Generate vector embeddings for chunks and store in Qdrant for semantic search.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `UUID` | string | Yes | File UUID or 'all' for all videos |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Vectorize chunks for one video
|
||||
momentry vectorize 384b0ff44aaaa1f1
|
||||
|
||||
# Vectorize all videos
|
||||
momentry vectorize all
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
**Note**: Vectorize requires Qdrant access.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `chunk` — Generate chunks before vectorizing
|
||||
- `query` — Query using vector embeddings
|
||||
- `phase1` — Full release pipeline
|
||||
43
docs_v1.0/doc_wasm/modules/109_CLI_Phase1.md
Normal file
43
docs_v1.0/doc_wasm/modules/109_CLI_Phase1.md
Normal file
@@ -0,0 +1,43 @@
|
||||
<!-- module: cli_phase1 -->
|
||||
<!-- description: Run Phase 1 release packaging -->
|
||||
<!-- depends: cli_process -->
|
||||
|
||||
# Phase1 — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry phase1 <UUID>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Execute the complete Phase 1 release pipeline for a video: process → chunk → vectorize → complete.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `UUID` | string | Yes | File UUID of the video |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Run Phase 1 release pipeline
|
||||
momentry phase1 384b0ff44aaaa1f1
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `process` — Process video
|
||||
- `chunk` — Generate chunks
|
||||
- `vectorize` — Vectorize chunks
|
||||
- `complete` — Mark video completed
|
||||
41
docs_v1.0/doc_wasm/modules/110_CLI_Complete.md
Normal file
41
docs_v1.0/doc_wasm/modules/110_CLI_Complete.md
Normal file
@@ -0,0 +1,41 @@
|
||||
<!-- module: cli_complete -->
|
||||
<!-- description: Mark video as completed -->
|
||||
<!-- depends: cli_phase1 -->
|
||||
|
||||
# Complete — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry complete <UUID>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Mark a video as fully processed and ready for production use.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `UUID` | string | Yes | File UUID of the video |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Mark video as completed
|
||||
momentry complete 384b0ff44aaaa1f1
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `phase1` — Full release pipeline
|
||||
- `status` — Check completion status
|
||||
46
docs_v1.0/doc_wasm/modules/111_CLI_Play.md
Normal file
46
docs_v1.0/doc_wasm/modules/111_CLI_Play.md
Normal file
@@ -0,0 +1,46 @@
|
||||
<!-- module: cli_play -->
|
||||
<!-- description: Play video with overlays -->
|
||||
<!-- depends: cli_process -->
|
||||
|
||||
# Play — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry play <TARGET>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Play a video with analysis overlays (face boxes, speaker labels, object detections).
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `TARGET` | string | Yes | Video path or UUID |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Play video by UUID
|
||||
momentry play 384b0ff44aaaa1f1
|
||||
|
||||
# Play video by path
|
||||
momentry play /path/to/video.mp4
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
**Note**: Play launches interactive video player.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `process` — Process video for overlays
|
||||
- `thumbnails` — Generate thumbnails
|
||||
47
docs_v1.0/doc_wasm/modules/112_CLI_Watch.md
Normal file
47
docs_v1.0/doc_wasm/modules/112_CLI_Watch.md
Normal file
@@ -0,0 +1,47 @@
|
||||
<!-- module: cli_watch -->
|
||||
<!-- description: Watch directories for new video files -->
|
||||
<!-- depends: none -->
|
||||
|
||||
# Watch — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry watch [OPTIONS]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Start watching specified directories for new video files and automatically register/process them.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `directories` | string | No | Directories to watch (comma separated) |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Watch default directory
|
||||
momentry watch
|
||||
|
||||
# Watch specific directories
|
||||
momentry watch /path/to/videos,/path/to/imports
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
**Note**: Watch runs as a long-running background service.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `register` — Manual registration
|
||||
- `process` — Manual processing
|
||||
- `worker` — Background job worker
|
||||
53
docs_v1.0/doc_wasm/modules/113_CLI_System.md
Normal file
53
docs_v1.0/doc_wasm/modules/113_CLI_System.md
Normal file
@@ -0,0 +1,53 @@
|
||||
<!-- module: cli_system -->
|
||||
<!-- description: Check system resources and processing strategy -->
|
||||
<!-- depends: none -->
|
||||
|
||||
# System — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry system [OPTIONS]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Check system resources (CPU, memory, GPU) and recommend optimal processing strategy.
|
||||
|
||||
## Arguments
|
||||
|
||||
None.
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Type | Required | Default | Description |
|
||||
|--------|------|----------|---------|-------------|
|
||||
| `--gpu` | bool | No | false | Show detailed GPU info (NVIDIA/MPS) |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Check basic system info
|
||||
momentry system
|
||||
|
||||
# Check with GPU details
|
||||
momentry system --gpu
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: `momentry system '<json-args>'`
|
||||
|
||||
**JSON Args**:
|
||||
```json
|
||||
{
|
||||
"gpu": true
|
||||
}
|
||||
```
|
||||
|
||||
**Returns**: JSON with system resource info.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `process` — Video processing
|
||||
- `worker` — Job worker configuration
|
||||
50
docs_v1.0/doc_wasm/modules/114_CLI_Server.md
Normal file
50
docs_v1.0/doc_wasm/modules/114_CLI_Server.md
Normal file
@@ -0,0 +1,50 @@
|
||||
<!-- module: cli_server -->
|
||||
<!-- description: Start API server -->
|
||||
<!-- depends: none -->
|
||||
|
||||
# Server — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry server [OPTIONS]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Start the Momentry API server for HTTP endpoints.
|
||||
|
||||
## Arguments
|
||||
|
||||
None.
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Type | Required | Default | Description |
|
||||
|--------|------|----------|---------|-------------|
|
||||
| `--host` | string | No | 127.0.0.1 | Server host address |
|
||||
| `--port` | u16 | No | MOMENTRY_SERVER_PORT or 3002 | Server port |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Start server on default port (3002)
|
||||
momentry server
|
||||
|
||||
# Start on custom port
|
||||
momentry server --port 3003
|
||||
|
||||
# Start on specific host
|
||||
momentry server --host 0.0.0.0 --port 3002
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
**Note**: Server runs as a long-running HTTP service.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `worker` — Start job worker
|
||||
- `api-key` — Manage API keys for server auth
|
||||
52
docs_v1.0/doc_wasm/modules/115_CLI_Worker.md
Normal file
52
docs_v1.0/doc_wasm/modules/115_CLI_Worker.md
Normal file
@@ -0,0 +1,52 @@
|
||||
<!-- module: cli_worker -->
|
||||
<!-- description: Start job worker for background processing -->
|
||||
<!-- depends: cli_server -->
|
||||
|
||||
# Worker — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry worker [OPTIONS]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Start the job worker to process queued jobs in the background.
|
||||
|
||||
## Arguments
|
||||
|
||||
None.
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Type | Required | Default | Description |
|
||||
|--------|------|----------|---------|-------------|
|
||||
| `--max-concurrent` | usize | No | 2 | Max concurrent processors |
|
||||
| `--poll-interval` | u64 | No | 5 | Poll interval in seconds |
|
||||
| `--batch-size` | i32 | No | 10 | Job batch size |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Start worker with defaults
|
||||
momentry worker
|
||||
|
||||
# Start with 6 concurrent processors
|
||||
momentry worker --max-concurrent 6
|
||||
|
||||
# Start with custom polling
|
||||
momentry worker --max-concurrent 4 --poll-interval 10 --batch-size 5
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
**Note**: Worker runs as a long-running background service.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `server` — API server
|
||||
- `process` — Manual processing
|
||||
- `watch` — Directory watcher
|
||||
54
docs_v1.0/doc_wasm/modules/116_CLI_Query.md
Normal file
54
docs_v1.0/doc_wasm/modules/116_CLI_Query.md
Normal file
@@ -0,0 +1,54 @@
|
||||
<!-- module: cli_query -->
|
||||
<!-- description: Query using RAG semantic search -->
|
||||
<!-- depends: cli_vectorize -->
|
||||
|
||||
# Query — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry query <QUERY>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Perform RAG (Retrieval-Augmented Generation) query against video content.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `QUERY` | string | Yes | Query text to search |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Simple query
|
||||
momentry query "What happened in the beginning?"
|
||||
|
||||
# Query about specific topic
|
||||
momentry query "Who is the main speaker?"
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: `momentry query '<json-args>'`
|
||||
|
||||
**JSON Args**:
|
||||
```json
|
||||
{
|
||||
"query": "What happened in the beginning?"
|
||||
}
|
||||
```
|
||||
|
||||
**Returns**: JSON with search results and answer.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `vectorize` — Vectorize chunks for search
|
||||
- `agent` — Agent-based intelligent query
|
||||
- `chunk` — Generate searchable chunks
|
||||
51
docs_v1.0/doc_wasm/modules/117_CLI_Lookup.md
Normal file
51
docs_v1.0/doc_wasm/modules/117_CLI_Lookup.md
Normal file
@@ -0,0 +1,51 @@
|
||||
<!-- module: cli_lookup -->
|
||||
<!-- description: Lookup UUID from file path -->
|
||||
<!-- depends: cli_register -->
|
||||
|
||||
# Lookup — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry lookup <PATH>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Lookup the UUID of a registered video from its file path.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `PATH` | string | Yes | File path of the registered video |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Lookup UUID from path
|
||||
momentry lookup /path/to/video.mp4
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: `momentry lookup '<json-args>'`
|
||||
|
||||
**JSON Args**:
|
||||
```json
|
||||
{
|
||||
"path": "/path/to/video.mp4"
|
||||
}
|
||||
```
|
||||
|
||||
**Returns**: JSON with `file_uuid`.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `resolve` — Resolve path from UUID
|
||||
- `register` — Register video file
|
||||
- `status` — Check video status
|
||||
51
docs_v1.0/doc_wasm/modules/118_CLI_Resolve.md
Normal file
51
docs_v1.0/doc_wasm/modules/118_CLI_Resolve.md
Normal file
@@ -0,0 +1,51 @@
|
||||
<!-- module: cli_resolve -->
|
||||
<!-- description: Resolve file path from UUID -->
|
||||
<!-- depends: cli_register -->
|
||||
|
||||
# Resolve — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry resolve <UUID>
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Resolve the file path of a registered video from its UUID.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `UUID` | string | Yes | File UUID of the video |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Resolve path from UUID
|
||||
momentry resolve 384b0ff44aaaa1f1
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: `momentry resolve '<json-args>'`
|
||||
|
||||
**JSON Args**:
|
||||
```json
|
||||
{
|
||||
"uuid": "384b0ff44aaaa1f1"
|
||||
}
|
||||
```
|
||||
|
||||
**Returns**: JSON with `file_path`.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `lookup` — Lookup UUID from path
|
||||
- `get_file_info` — Agent tool for file info
|
||||
- `status` — Check video status
|
||||
57
docs_v1.0/doc_wasm/modules/119_CLI_Thumbnails.md
Normal file
57
docs_v1.0/doc_wasm/modules/119_CLI_Thumbnails.md
Normal file
@@ -0,0 +1,57 @@
|
||||
<!-- module: cli_thumbnails -->
|
||||
<!-- description: Generate thumbnails for videos -->
|
||||
<!-- depends: cli_process -->
|
||||
|
||||
# Thumbnails — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry thumbnails [UUID] [OPTIONS]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Generate thumbnail images for video preview.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `UUID` | string | No | File UUID (generates for all if not specified) |
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Type | Required | Default | Description |
|
||||
|--------|------|----------|---------|-------------|
|
||||
| `-c, --count` | u32 | No | 6 | Number of thumbnails per video |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Generate thumbnails for all videos
|
||||
momentry thumbnails
|
||||
|
||||
# Generate 10 thumbnails for specific video
|
||||
momentry thumbnails 384b0ff44aaaa1f1 --count 10
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: `momentry thumbnails '<json-args>'`
|
||||
|
||||
**JSON Args**:
|
||||
```json
|
||||
{
|
||||
"uuid": "384b0ff44aaaa1f1",
|
||||
"count": 6
|
||||
}
|
||||
```
|
||||
|
||||
**Returns**: JSON with thumbnail paths.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `process` — Process video first
|
||||
- `play` — Play video with overlays
|
||||
- `get_representative_frame` — Agent tool for best frame
|
||||
54
docs_v1.0/doc_wasm/modules/120_CLI_Status.md
Normal file
54
docs_v1.0/doc_wasm/modules/120_CLI_Status.md
Normal file
@@ -0,0 +1,54 @@
|
||||
<!-- module: cli_status -->
|
||||
<!-- description: Show storage status report -->
|
||||
<!-- depends: cli_register -->
|
||||
|
||||
# Status — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry status [UUID]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Show storage and processing status report for registered videos.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `UUID` | string | No | File UUID (shows all if not specified) |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Show status for all videos
|
||||
momentry status
|
||||
|
||||
# Show status for specific video
|
||||
momentry status 384b0ff44aaaa1f1
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: `momentry status '<json-args>'`
|
||||
|
||||
**JSON Args**:
|
||||
```json
|
||||
{
|
||||
"uuid": "384b0ff44aaaa1f1"
|
||||
}
|
||||
```
|
||||
|
||||
**Returns**: JSON with status info.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `register` — Register video
|
||||
- `process` — Process video
|
||||
- `complete` — Mark completed
|
||||
61
docs_v1.0/doc_wasm/modules/121_CLI_Backup.md
Normal file
61
docs_v1.0/doc_wasm/modules/121_CLI_Backup.md
Normal file
@@ -0,0 +1,61 @@
|
||||
<!-- module: cli_backup -->
|
||||
<!-- description: Manage output backups -->
|
||||
<!-- depends: none -->
|
||||
|
||||
# Backup — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry backup <ACTION> [OPTIONS]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Manage backup files in the output directory.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `ACTION` | string | Yes | Action: list, cleanup |
|
||||
| `days` | u32 | No | Days to keep (for cleanup) |
|
||||
|
||||
## Options
|
||||
|
||||
None.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# List backup files
|
||||
momentry backup list
|
||||
|
||||
# Cleanup backups older than 30 days
|
||||
momentry backup cleanup 30
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: `momentry backup '<json-args>'`
|
||||
|
||||
**JSON Args**:
|
||||
```json
|
||||
{
|
||||
"action": "list"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "cleanup",
|
||||
"days": 30
|
||||
}
|
||||
```
|
||||
|
||||
**Returns**: JSON with backup info or cleanup results.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `status` — Storage status
|
||||
- `process` — Generates output files
|
||||
64
docs_v1.0/doc_wasm/modules/122_CLI_ApiKey.md
Normal file
64
docs_v1.0/doc_wasm/modules/122_CLI_ApiKey.md
Normal file
@@ -0,0 +1,64 @@
|
||||
<!-- module: cli_api_key -->
|
||||
<!-- description: Manage API keys for authentication -->
|
||||
<!-- depends: cli_server -->
|
||||
|
||||
# Api-Key — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry api-key <ACTION> [OPTIONS]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Manage API keys for server authentication and access control.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `ACTION` | enum | Yes | Action: create, list, validate, revoke, rotate, stats |
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Type | Required | Description |
|
||||
|--------|------|----------|-------------|
|
||||
| `--name` | string | No | Key name (for create) |
|
||||
| `--key-type` | string | No | Key type: system, user, service, integration, emergency |
|
||||
| `--ttl` | i64 | No | TTL in days (for create) |
|
||||
| `--key` | string | No | API key to validate/revoke |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Create a new API key
|
||||
momentry api-key create --name "my-service" --key-type service --ttl 365
|
||||
|
||||
# List all API keys
|
||||
momentry api-key list
|
||||
|
||||
# Validate an API key
|
||||
momentry api-key validate --key muser_xxx
|
||||
|
||||
# Revoke an API key
|
||||
momentry api-key revoke --key muser_xxx
|
||||
|
||||
# Rotate an API key
|
||||
momentry api-key rotate --key muser_xxx
|
||||
|
||||
# Show API key statistics
|
||||
momentry api-key stats
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
**Note**: API key management is admin-level operation.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `server` — API server using these keys
|
||||
- `gitea` — Manage Gitea tokens
|
||||
- `n8n` — Manage n8n API keys
|
||||
57
docs_v1.0/doc_wasm/modules/123_CLI_Gitea.md
Normal file
57
docs_v1.0/doc_wasm/modules/123_CLI_Gitea.md
Normal file
@@ -0,0 +1,57 @@
|
||||
<!-- module: cli_gitea -->
|
||||
<!-- description: Manage Gitea API tokens -->
|
||||
<!-- depends: none -->
|
||||
|
||||
# Gitea — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry gitea <ACTION> [OPTIONS]
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Manage Gitea API tokens for repository sync.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `ACTION` | enum | Yes | Action: create, list, delete, verify |
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Type | Required | Description |
|
||||
|--------|------|----------|-------------|
|
||||
| `--username` | string | No | Gitea username (for create/list/delete) |
|
||||
| `--password` | string | No | Gitea password (for create/list/delete) |
|
||||
| `--token-name` | string | No | Token name (for create/delete) |
|
||||
| `--scopes` | string | No | Token scopes (comma separated: read:repository,write:issue) |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Create a Gitea token
|
||||
momentry gitea create --username admin --password secret --token-name "ci-token" --scopes write:repository
|
||||
|
||||
# List tokens
|
||||
momentry gitea list --username admin --password secret
|
||||
|
||||
# Verify a token
|
||||
momentry gitea verify --token-name "ci-token"
|
||||
|
||||
# Delete a token
|
||||
momentry gitea delete --username admin --password secret --token-name "ci-token"
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Not directly callable via agent JSON args.
|
||||
|
||||
**Note**: Gitea token management requires admin credentials.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `api-key` — Manage Momentry API keys
|
||||
- `n8n` — Manage n8n API keys
|
||||
74
docs_v1.0/doc_wasm/modules/124_CLI_Agent.md
Normal file
74
docs_v1.0/doc_wasm/modules/124_CLI_Agent.md
Normal file
@@ -0,0 +1,74 @@
|
||||
<!-- module: cli_agent -->
|
||||
<!-- description: Run agent tools with JSON arguments -->
|
||||
<!-- depends: cli_vectorize -->
|
||||
|
||||
# Agent — CLI Command
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
momentry agent <TOOL> '<JSON_ARGS>'
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
Run an agent tool directly from CLI with JSON arguments. Same interface as LLM function calling.
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `TOOL` | string | Yes | Tool name (find_file, list_files, tkg_query, etc.) |
|
||||
| `ARGS` | string | Yes | JSON arguments for the tool |
|
||||
|
||||
## Available Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `find_file` | Search files by keyword |
|
||||
| `list_files` | List recent files |
|
||||
| `tkg_query` | Query TKG (top_identities, speaker_dialogue, etc.) |
|
||||
| `tkg_nodes_query` | Query TKG nodes |
|
||||
| `tkg_edges_query` | Query TKG edges |
|
||||
| `tkg_node_detail` | Query single TKG node |
|
||||
| `smart_search` | Semantic search chunks |
|
||||
| `identity_text` | Search text to find identities |
|
||||
| `identities_search` | Search identity dialogue |
|
||||
| `get_identity_detail` | Get identity details |
|
||||
| `get_file_info` | Get file metadata |
|
||||
| `get_representative_frame` | Get representative frame |
|
||||
| `analyze_frame` | Analyze frame with vision LLM |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# List recent files
|
||||
momentry agent list_files '{}'
|
||||
|
||||
# Find files by keyword
|
||||
momentry agent find_file '{"query":"batman"}'
|
||||
|
||||
# Get file info
|
||||
momentry agent get_file_info '{"file_uuid":"384b0ff44aaaa1f1"}'
|
||||
|
||||
# Query top identities
|
||||
momentry agent tkg_query '{"file_uuid":"384b0ff44aaaa1f1","query_type":"top_identities"}'
|
||||
|
||||
# Smart search
|
||||
momentry agent smart_search '{"query":"action scene","limit":5}'
|
||||
|
||||
# Analyze frame
|
||||
momentry agent analyze_frame '{"file_uuid":"384b0ff44aaaa1f1","question":"What is happening?"}'
|
||||
```
|
||||
|
||||
## Agent Callable
|
||||
|
||||
**Format**: Direct CLI invocation — agent tools are designed for this.
|
||||
|
||||
**Returns**: JSON string with tool results.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `query` — Basic RAG query
|
||||
- `tkg_query` — TKG API endpoint
|
||||
- `smart_search` — Search API endpoint
|
||||
148
docs_v1.0/doc_wasm/modules/16_workspace.md
Normal file
148
docs_v1.0/doc_wasm/modules/16_workspace.md
Normal file
@@ -0,0 +1,148 @@
|
||||
<!-- module: workspace -->
|
||||
<!-- description: Workspace checkout/checkin — lock, clear, restore file data -->
|
||||
<!-- depends: 04_lookup, 05_process -->
|
||||
|
||||
## Workspace Checkin/Checkout
|
||||
|
||||
Workspace checkin/checkout provides a transactional editing model for file data:
|
||||
- **Checkout**: Clears PG tables (face_detections, speaker_detections, pre_chunks) and Qdrant vectors, creating an isolated workspace SQLite for editing.
|
||||
- **Checkin**: Restores data from the workspace SQLite back to PG and Qdrant, marking the file as `Indexed`.
|
||||
|
||||
This allows safe concurrent editing — while a file is checked out, its main database records are cleared, preventing conflicts.
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/file/:file_uuid/checkout`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Checkout a file workspace. Clears face detections, speaker detections, pre_chunks from PostgreSQL, deletes Qdrant vectors, and creates a workspace SQLite database for isolated editing.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/file/$FILE_UUID/checkout" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"rows_deleted": 1523,
|
||||
"status": "checked_out"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `file_uuid` | string | 32-char hex UUID |
|
||||
| `rows_deleted` | integer | Total rows cleared from PG tables |
|
||||
| `status` | string | `"checked_out"` |
|
||||
|
||||
#### Error Responses
|
||||
|
||||
| HTTP | When |
|
||||
|------|------|
|
||||
| `500` | Checkout failed (DB error, workspace creation error) |
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/file/:file_uuid/checkin`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Checkin a file workspace. Restores face detections, speaker detections, pre_chunks from workspace SQLite back to PostgreSQL, re-indexes vectors to Qdrant, and sets video status to `Indexed`.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/file/$FILE_UUID/checkin" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"pre_chunks_moved": 45,
|
||||
"face_detections_moved": 1200,
|
||||
"speaker_detections_moved": 320,
|
||||
"vectors_moved": 45,
|
||||
"status": "indexed"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `file_uuid` | string | 32-char hex UUID |
|
||||
| `pre_chunks_moved` | integer | Pre-chunks restored from workspace |
|
||||
| `face_detections_moved` | integer | Face detections restored from workspace |
|
||||
| `speaker_detections_moved` | integer | Speaker detections restored from workspace |
|
||||
| `vectors_moved` | integer | Vectors re-indexed to Qdrant |
|
||||
| `status` | string | `"indexed"` |
|
||||
|
||||
#### Error Responses
|
||||
|
||||
| HTTP | When |
|
||||
|------|------|
|
||||
| `500` | Checkin failed (DB error, workspace not found, vector index error) |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/workspace`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Check if a workspace SQLite database exists for a file.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/file/$FILE_UUID/workspace" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
|
||||
"exists": true
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `file_uuid` | string | 32-char hex UUID |
|
||||
| `exists` | boolean | True if workspace SQLite exists |
|
||||
|
||||
---
|
||||
|
||||
### Workflow
|
||||
|
||||
```
|
||||
REGISTERED ──→ CHECKED_OUT ──→ INDEXED
|
||||
│ │ │
|
||||
│ checkout checkin
|
||||
│ │ │
|
||||
│ clear PG + Qdrant restore from SQLite
|
||||
│ create workspace re-index vectors
|
||||
│ set status set status
|
||||
```
|
||||
|
||||
1. **Register** file → status: `REGISTERED`
|
||||
2. **Process** file → processors run, data stored in PG + Qdrant
|
||||
3. **Checkout** file → clear editable data, create workspace SQLite → status: `CHECKED_OUT`
|
||||
4. **Edit** workspace via Agent Search / identity binding
|
||||
5. **Checkin** file → restore from workspace SQLite → status: `INDEXED`
|
||||
6. **Rebuild TKG** if needed after checkin
|
||||
|
||||
---
|
||||
|
||||
*Updated: 2026-06-20 12:00:00*
|
||||
188
docs_v1.0/doc_wasm/modules/99_incomplete.md
Normal file
188
docs_v1.0/doc_wasm/modules/99_incomplete.md
Normal file
@@ -0,0 +1,188 @@
|
||||
<!-- module: incomplete -->
|
||||
<!-- description: Incomplete, stub, or undocumented API endpoints — tracking list -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
## Incomplete / Undocumented APIs
|
||||
|
||||
This module tracks API endpoints that exist in the codebase but are either undocumented, partially documented, or stubs.
|
||||
|
||||
> **Note**: Endpoints listed here should be fully documented and moved to their appropriate module once implemented.
|
||||
|
||||
---
|
||||
|
||||
## Identity Binding
|
||||
|
||||
### `POST /api/v1/identity/:identity_uuid/bind`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Bind a single face detection to an identity. Unlike `bind/trace` which binds all faces in a trace, this binds one specific face.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `file_uuid` | string | Yes | File containing the face |
|
||||
| `face_id` | string | Yes | Face detection ID to bind |
|
||||
|
||||
#### Status
|
||||
|
||||
⚠️ **Undocumented** — exists in code but no full request/response documentation.
|
||||
|
||||
---
|
||||
|
||||
## Resource Management
|
||||
|
||||
### `POST /api/v1/resource/register`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
Register an external resource (e.g., storage backend, API service).
|
||||
|
||||
#### Status
|
||||
|
||||
⚠️ **Undocumented** — endpoint exists but no documentation.
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/resource/heartbeat`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
Send heartbeat for a registered resource to verify it's still alive.
|
||||
|
||||
#### Status
|
||||
|
||||
⚠️ **Undocumented** — endpoint exists but no documentation.
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/resources`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
List all registered resources with their status.
|
||||
|
||||
#### Status
|
||||
|
||||
⚠️ **Undocumented** — endpoint exists but no documentation.
|
||||
|
||||
---
|
||||
|
||||
## 5W1H Agent
|
||||
|
||||
### `POST /api/v1/agents/5w1h/analyze`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Run 5W1H analysis on all cut scenes for a file. Uses LLM (Gemma4) to summarize each scene with who/what/where/when/why/how.
|
||||
|
||||
#### Status
|
||||
|
||||
⚠️ **Partially documented** — listed in `12_agent.md` but missing full request/response examples.
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/agents/5w1h/batch`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
Run 5W1H analysis on multiple files at once.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `file_uuids` | string[] | Yes | Array of file UUIDs to analyze |
|
||||
|
||||
#### Status
|
||||
|
||||
⚠️ **Partially documented** — listed in `12_agent.md` but missing full request/response examples.
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/agents/5w1h/status`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
Get 5W1H analysis status across all videos (which files have been analyzed, which are pending).
|
||||
|
||||
#### Status
|
||||
|
||||
⚠️ **Partially documented** — listed in `12_agent.md` but missing full response schema.
|
||||
|
||||
---
|
||||
|
||||
## Identity Agent
|
||||
|
||||
### `POST /api/v1/agents/identity/match-from-photo`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
Match an identity using an uploaded photo. Extracts face embedding, finds best trace match.
|
||||
|
||||
#### Status
|
||||
|
||||
⚠️ **Partially documented** — exists in `08_identity_agent.md` but missing full response schema and error cases.
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/agents/identity/match-from-trace`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Match an identity using a trace. Multi-angle embedding comparison with propagation.
|
||||
|
||||
#### Status
|
||||
|
||||
⚠️ **Partially documented** — exists in `08_identity_agent.md` but missing full response schema and error cases.
|
||||
|
||||
---
|
||||
|
||||
## Stubs / Not Implemented
|
||||
|
||||
### Visual Search Endpoints
|
||||
|
||||
| Method | Endpoint | Status |
|
||||
|--------|----------|--------|
|
||||
| POST | `/api/v1/search/visual` | Stub — defined but not functional |
|
||||
| POST | `/api/v1/search/visual/class` | Stub — defined but not functional |
|
||||
| POST | `/api/v1/search/visual/density` | Stub — defined but not functional |
|
||||
| POST | `/api/v1/search/visual/combination` | Stub — defined but not functional |
|
||||
| POST | `/api/v1/search/visual/stats` | Stub — defined but not functional |
|
||||
|
||||
### Unmounted Routes
|
||||
|
||||
These endpoints are defined in source code but not mounted in the router:
|
||||
|
||||
| Endpoint | Notes |
|
||||
|----------|-------|
|
||||
| `/api/v1/search/persons` | Defined but not mounted |
|
||||
| `/api/v1/who` | Defined but not mounted |
|
||||
| `/api/v1/who/candidates` | Defined but not mounted |
|
||||
|
||||
---
|
||||
|
||||
## Tracking
|
||||
|
||||
| Count | Status |
|
||||
|-------|--------|
|
||||
| Undocumented | 3 (resource management) |
|
||||
| Partially documented | 5 (5W1H ×3, identity agent ×2) |
|
||||
| Stub/not functional | 5 (visual search) |
|
||||
| Defined but unmounted | 3 (persons, who, who/candidates) |
|
||||
| **Total** | **16** |
|
||||
|
||||
---
|
||||
|
||||
*Created: 2026-06-20 — Gap analysis from core API vs doc_wasm sync*
|
||||
*Updated: 2026-06-20 — Initial tracking list*
|
||||
63
docs_v1.0/doc_wasm/modules/_template.md
Normal file
63
docs_v1.0/doc_wasm/modules/_template.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# {Module Name} — API Workspace Module
|
||||
|
||||
> Use this template when adding or editing API endpoint documentation modules.
|
||||
|
||||
## Module Metadata
|
||||
|
||||
Every module MUST start with:
|
||||
|
||||
```markdown
|
||||
<!-- module: <short_name> -->
|
||||
<!-- description: One-line description of what this module covers -->
|
||||
<!-- depends: <comma-separated list of dependency module names> -->
|
||||
```
|
||||
|
||||
## Endpoint Template
|
||||
|
||||
Each endpoint MUST use this structure:
|
||||
|
||||
### `METHOD /path/to/endpoint`
|
||||
|
||||
**Auth**: Required / Optional / Public
|
||||
|
||||
**Scope**: file-level / identity-level / system-level
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `param1` | string | Yes | — | Description |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# brief description of what this example demonstrates
|
||||
curl -s -X METHOD "$API/path" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"param1": "value"}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{ "success": true }
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `success` | boolean | Always true on 200 |
|
||||
|
||||
#### Error Codes
|
||||
|
||||
| Code | HTTP | When |
|
||||
|------|------|------|
|
||||
| E0xx | 4xx | Description |
|
||||
|
||||
## Rules
|
||||
|
||||
1. Each module file covers ONE topic group (e.g., `09_tmdb.md` = all TMDb endpoints)
|
||||
2. Use `$API` and `$KEY` in all curl examples
|
||||
3. Use `$FILE_UUID`, `$IDENTITY_UUID` variables for UUID examples
|
||||
4. Module filename = `NN_topic.md` (NN = execution order, 01-99)
|
||||
5. `depends` metadata = which modules must be assembled before this one
|
||||
Reference in New Issue
Block a user