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

deliverable_v1.1.0/modules/06_search.md

@@ -0,0 +1,145 @@
+<!-- module: search -->
+<!-- description: Vector search, BM25, smart search, universal search, visual search -->
+<!-- depends: 01_auth -->
+
+## Search APIs
+
+### `POST /api/v1/search/smart`
+
+**Auth**: Required
+**Scope**: file-level
+
+Semantic vector search using EmbeddingGemma-300m. Generates a query embedding via EmbeddingGemma (port 11436), then searches pgvector `story_parent` and `llm_parent` chunks by cosine similarity.
+
+#### Request Parameters
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `file_uuid` | string | Yes | — | File UUID to search within |
+| `query` | string | Yes | — | Search text |
+| `limit` | integer | No | 5 | Max results to return |
+| `page` | integer | No | 1 | Page number |
+| `page_size` | integer | No | 5 | Items per page |
+
+#### Example
+
+```bash
+curl -s -X POST "$API/api/v1/search/smart" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $JWT" \
+  -d '{"file_uuid": "'"$FILE_UUID"'", "query": "Audrey Hepburn"}'
+```
+
+#### Response (200)
+
+```json
+{
+  "query": "Audrey Hepburn",
+  "results": [
+    {
+      "parent_id": 1087822,
+      "scene_order": 1087822,
+      "start_frame": 104438,
+      "end_frame": 104538,
+      "fps": 24.0,
+      "start_time": 4351.6,
+      "end_time": 4355.76,
+      "summary": "[4352s-4356s, 4s] Cast: Audrey Hepburn. Total: 2 lines, 10 words. Speakers: Audrey Hepburn (2 lines)",
+      "similarity": 0.67
+    }
+  ],
+  "page": 1,
+  "page_size": 5,
+  "strategy": "semantic_vector_search"
+}
+```
+
+---
+
+### `POST /api/v1/search/universal`
+
+**Auth**: Required
+**Scope**: file-level
+
+Multi-type BM25 full-text search across chunks, frames, and persons. Uses PostgreSQL `tsvector`.
+
+#### Request Parameters
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `query` | string | Yes | — | Search text |
+| `file_uuid` | string | No | — | Restrict to specific file |
+| `types` | string[] | No | `["chunk","frame","person"]` | Search types |
+| `limit` | integer | No | 10 | Max results per type |
+| `page` | integer | No | 1 | Page number |
+| `page_size` | integer | No | 20 | Items per page |
+
+#### Example
+
+```bash
+curl -s -X POST "$API/api/v1/search/universal" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $JWT" \
+  -d '{"file_uuid": "'"$FILE_UUID"'", "query": "Cary Grant"}'
+```
+
+#### Response (200)
+
+```json
+{
+  "results": [
+    {
+      "type": "chunk",
+      "chunk_id": "bd80fec92b0b6963d177a2c55bf713e2_2",
+      "chunk_type": "story_child",
+      "start_frame": 5103,
+      "end_frame": 5127,
+      "start_time": 212.64,
+      "end_time": 213.64,
+      "text": "[213s-214s] Cary Grant: \"Olá!\"",
+      "score": 0.9
+    }
+  ],
+  "total": 20,
+  "took_ms": 18
+}
+```
+
+---
+
+### `POST /api/v1/search/frames`
+
+**Auth**: Required
+**Scope**: file-level
+
+Search face detection frames by identity name or trace ID.
+
+---
+
+### `POST /api/v1/search/identity_text`
+
+**Auth**: Required
+**Scope**: file-level
+
+Search text chunks spoken by a specific identity.
+
+---
+
+### Visual Search
+
+| 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 |
+
+#### Embedding Model
+
+| Detail | Value |
+|--------|-------|
+| **Model** | EmbeddingGemma-300m |
+| **Endpoint** | `POST /api/v1/embeddings` on port 11436 |
+| **Dimension** | 768 |
+| **Storage** | pgvector (`chunk.embedding` column) |