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

deliverable_v1.1.0/modules/12_agent.md

@@ -0,0 +1,118 @@
+# Agent Endpoints
+
+Agent endpoints provide AI-powered capabilities including translation, identity analysis, and 5W1H extraction.
+
+## POST /api/v1/agents/translate
+
+Translate text between languages using Gemma4 (llama.cpp, port 8082).
+
+### Request
+
+```json
+{
+  "text": "Hello, welcome to Momentry Core.",
+  "target_language": "Traditional Chinese",
+  "source_language": "English"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `text` | string | ✅ | Text to translate |
+| `target_language` | string | ✅ | Target language name (e.g. "Traditional Chinese", "Japanese") |
+| `source_language` | string | ❌ | Source language (default: "auto") |
+
+### Response
+
+```json
+{
+  "success": true,
+  "translated_text": "您好，歡迎使用 Momentry Core。",
+  "source_language_detected": "English",
+  "model_used": "google_gemma-4-26B-A4B-it-Q5_K_M.gguf"
+}
+```
+
+### Supported Language Pairs (tested)
+
+| Source | Target | Quality |
+|--------|--------|---------|
+| English | Traditional Chinese | ✅ |
+| English | Japanese | ✅ |
+| Chinese | English | ✅ |
+| English | French | ✅ |
+| Chinese | Japanese | ✅ |
+
+### Model
+
+- **Model**: Gemma4 26B (Q5_K_M)
+- **Engine**: llama.cpp at `localhost:8082`
+- **Endpoint**: `/v1/chat/completions` (OpenAI-compatible)
+- **Temperature**: 0.1
+- **Max tokens**: 1024
+
+### Errors
+
+| Status | Condition |
+|--------|-----------|
+| 500 | LLM unreachable or response parse failure |
+| 401 | Missing/invalid auth |
+
+---
+
+## POST /api/v1/agents/5w1h/analyze
+
+Extract 5W1H (Who, What, When, Where, Why, How) from a scene. Uses Gemma4 LLM on port 8082.
+
+### Request
+
+```json
+{
+  "file_uuid": "3abeee81d94597629ed8cb943f182e94",
+  "scene_id": 42
+}
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "5w1h": {
+    "who": ["Cary Grant"],
+    "what": ["discussing plans"],
+    "when": ["1963"],
+    "where": ["Paris"],
+    "why": ["vacation"],
+    "how": ["in person"]
+  }
+}
+```
+
+## POST /api/v1/agents/5w1h/batch
+
+Batch analyze all scenes in a file for 5W1H extraction. Uses the pipeline's `parent_chunk_5w1h.py --mode llm`.
+
+### Request
+
+```json
+{
+  "file_uuid": "3abeee81d94597629ed8cb943f182e94"
+}
+```
+
+## GET /api/v1/agents/5w1h/status
+
+Get status of the 5W1H agent pipeline for a file.
+
+---
+
+## Embedding Model
+
+| Detail | Value |
+|--------|-------|
+| **Model** | EmbeddingGemma-300m |
+| **Endpoint** | `POST /v1/embeddings` on port 11436 |
+| **Dimension** | 768 |
+| **Used by** | `parent_chunk_5w1h.py --embed`, story, 5W1H, search |
+