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

deliverable_v1.1.0/modules/09_tmdb.md

@@ -0,0 +1,109 @@
+<!-- module: tmdb -->
+<!-- description: TMDb enrichment endpoints — prefetch, probe, resource, check -->
+<!-- depends: 01_auth, 03_register -->
+
+## TMDb Enrichment
+
+> **Offline operation**: TMDb prefetch now checks local identity files first (`identities/_index.json` + `*.tmdb.json`).
+> If local files exist, no external API call is made. Internet is only needed for initial data seeding.
+
+### Overview
+
+TMDb enrichment is an optional identity enrichment step that can be run after Pipeline face detection completes. The workflow is:
+
+1. **Prefetch** (requires internet): Download movie cast data from TMDb API → cache to `{file_uuid}.tmdb.json`
+2. **Probe**: Read local cache → create identities for **all** cast members (`source='tmdb'`) + save `identity.json` + download profile image to `{OUTPUT}/identities/{uuid}/profile.jpg`
+3. **Match**: The worker automatically matches video faces against TMDb identities when `MOMENTRY_TMDB_PROBE_ENABLED=true`
+
+### `POST /api/v1/agents/tmdb/prefetch`
+
+**Auth**: Required
+**Scope**: file-level
+
+Fetch TMDb cast data for a registered file and cache it locally. This is the only step requiring internet access.
+
+#### Request Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file_uuid` | string | Yes | File UUID to enrich |
+
+#### Example
+
+```bash
+curl -s -X POST "$API/api/v1/agents/tmdb/prefetch" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: $KEY" \
+  -d '{"file_uuid": "'"$FILE_UUID"'"}'
+```
+
+#### Response (200)
+
+```json
+{"success": true, "file_uuid": "...", "cache_path": "/output/...tmdb.json"}
+```
+
+### `POST /api/v1/file/:file_uuid/tmdb-probe`
+
+**Auth**: Required
+**Scope**: file-level
+
+Read local TMDb cache and create/update identities. Requires prefetch to have been run first.
+
+#### Example
+
+```bash
+curl -s -X POST "$API/api/v1/file/$FILE_UUID/tmdb-probe" \
+  -H "X-API-Key: $KEY" | jq '{identities_created, movie_title}'
+```
+
+#### Response (200 — identities created)
+
+```json
+{"success": true, "identities_created": 15, "movie_title": "Charade"}
+```
+
+#### Response (200 — no cache)
+
+```json
+{"success": false, "message": "No TMDb cache found. Run tmdb-prefetch first."}
+```
+
+### `GET /api/v1/resource/tmdb`
+
+**Auth**: Required
+**Scope**: system-level
+
+View TMDb resource status including configuration, identity counts, and cache file count.
+
+#### Example
+
+```bash
+curl -s "$API/api/v1/resource/tmdb" -H "X-API-Key: $KEY" \
+  | jq '{identities_seeded, cache_files}'
+```
+
+### `POST /api/v1/resource/tmdb/check`
+
+**Auth**: Required
+**Scope**: system-level
+
+Ping the TMDb API to verify connectivity and measure latency.
+
+#### Example
+
+```bash
+curl -s -X POST "$API/api/v1/resource/tmdb/check" \
+  -H "X-API-Key: $KEY" | jq '.status'
+```
+
+#### Response
+
+```json
+{
+  "api_key_configured": true,
+  "enabled": false,
+  "api_reachable": true,
+  "api_latency_ms": 120
+}
+```