# 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 |