<!-- 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) |