feat: ASRX hybrid pipeline, identity history, worker fixes, checkpoint system

deliverable_v1.1.0/modules/04_lookup.md

@@ -0,0 +1,138 @@
+<!-- module: lookup -->
+<!-- description: File lookup by name and unregistration -->
+<!-- depends: 01_auth, 03_register -->
+
+## File Lookup
+
+### `GET /api/v1/files/lookup`
+
+**Auth**: Required
+**Scope**: file-level
+
+Search registered files by file name. Performs a case-insensitive LIKE search on the file name column. Returns basic info about matching files.
+
+#### Query Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file_name` | string | Yes | File name to search for (partial matches supported) |
+
+#### Example
+
+```bash
+# Look up a specific file
+curl -s "$API/api/v1/files/lookup?file_name=video.mp4" \
+  -H "X-API-Key: $KEY"
+
+# Partial name search
+curl -s "$API/api/v1/files/lookup?file_name=charade" \
+  -H "X-API-Key: $KEY" | jq '.matches[].file_name'
+```
+
+#### Response (200)
+
+```json
+{
+  "file_name": "video.mp4",
+  "exists": true,
+  "matches": [
+    {
+      "file_uuid": "a03485a40b2df2d3",
+      "file_name": "video.mp4",
+      "file_type": "video",
+      "status": "completed"
+    }
+  ],
+  "next_name": "video (2).mp4"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `file_name` | string | Searched name |
+| `exists` | boolean | Exact name match exists |
+| `matches` | array | Array of matching registered files |
+| `matches[].file_uuid` | string | 32-char hex UUID |
+| `matches[].file_name` | string | Registered file name |
+| `matches[].file_type` | string | `"video"`, `"audio"`, or `null` |
+| `matches[].status` | string | Registration/processing status |
+| `next_name` | string | Suggested name for avoiding conflicts |
+
+---
+
+## Unregister
+
+### `POST /api/v1/unregister`
+
+**Auth**: Required
+**Scope**: file-level
+
+Delete a registered file from the system. Supports single file by UUID, or batch by directory + regex pattern.
+
+#### What gets deleted
+
+| Removed (default) | Not removed |
+|---------|-------------|
+| Database records (videos, chunks, embeddings, processor_results, pre_chunks) | The original source video file on disk |
+| Processor output JSON files (`{uuid}.*.json`) — unless `delete_output_files: false` | Temp/working directories |
+| In-memory cache entries | |
+| MongoDB cached lists | |
+
+> ⚠️ Database deletion is **irreversible**. To keep output files, set `"delete_output_files": false`.
+
+#### Request Parameters
+
+At least one mode must be specified: either `file_uuid` alone, or `file_path` + `pattern` together.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `file_uuid` | string | * | — | Single file UUID to delete |
+| `file_path` | string | * | — | Directory path (for batch delete) |
+| `pattern` | string | * | — | Regex pattern (requires `file_path`) |
+| `delete_output_files` | boolean | No | `true` | If `true`, also delete processor output JSON files (`{uuid}.*.json`). Set to `false` to keep them. |
+
+#### Example
+
+```bash
+# Delete a single file by UUID (default: also deletes output JSON files)
+curl -s -X POST "$API/api/v1/unregister" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: $KEY" \
+  -d '{"file_uuid": "'"$FILE_UUID"'"}'
+
+# Keep output JSON files, only delete DB records
+curl -s -X POST "$API/api/v1/unregister" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: $KEY" \
+  -d '{"file_uuid": "'"$FILE_UUID"'", "delete_output_files": false}'
+
+# Batch delete all mp4 files in a directory
+curl -s -X POST "$API/api/v1/unregister" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: $KEY" \
+  -d '{"file_path": "/path/to/dir", "pattern": ".*\\.mp4$"}'
+```
+
+#### Response (200)
+
+```json
+{
+  "success": true,
+  "file_uuid": "a03485a40b2df2d3",
+  "message": "Video unregistered successfully"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | True if deletion succeeded |
+| `file_uuid` | string | UUID of the deleted file (single mode) |
+| `message` | string | Human-readable status |
+
+#### Error Responses
+
+| HTTP | When |
+|------|------|
+| `400` | Neither `file_uuid` nor `file_path`+`pattern` provided |
+| `404` | File UUID not found |
+| `401` | Missing or invalid API key |