From a78b5bc12b2e072f57b42ddef77c4289d1994178 Mon Sep 17 00:00:00 2001
From: Accusys <accusys@momentry.dev>
Date: Fri, 22 May 2026 12:26:11 +0800
Subject: [PATCH] docs: add agents/search endpoint to 12_agent.md

---
 docs_v1.0/API_WORKSPACE/modules/12_agent.md | 92 ++++++++++++++++++++-
 docs_v1.0/doc_wasm/modules/12_agent.md      | 92 ++++++++++++++++++++-
 2 files changed, 182 insertions(+), 2 deletions(-)

diff --git a/docs_v1.0/API_WORKSPACE/modules/12_agent.md b/docs_v1.0/API_WORKSPACE/modules/12_agent.md
index 8793ad3..cdc5fe0 100644
--- a/docs_v1.0/API_WORKSPACE/modules/12_agent.md
+++ b/docs_v1.0/API_WORKSPACE/modules/12_agent.md
@@ -116,6 +116,96 @@ Get status of the 5W1H agent pipeline for a file.
 | **Dimension** | 768 |
 | **Used by** | `parent_chunk_5w1h.py --embed`, story, 5W1H, search |
 
+---
+
+## POST /api/v1/agents/search
+
+Conversational search assistant. Uses Gemma4 function calling to automatically decide which tools to call based on the user's natural language query. Supports multi-turn conversation.
+
+### Request
+
+```json
+{
+  "query": "Audrey Hepburn 和 Cary Grant 第一次同框在哪個 frame？",
+  "conversation_id": null,
+  "file_uuid": null
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `query` | string | ✅ | 自然語言查詢 |
+| `conversation_id` | string | ❌ | 延續對話時傳入；新對話不傳 |
+| `file_uuid` | string | ❌ | Portal 有選中檔案時可指定 |
+
+### Response
+
+```json
+{
+  "success": true,
+  "conversation_id": "conv_abc123",
+  "answer": "在 Charade (1963) 中，Audrey Hepburn 與 Cary Grant 第一次同框在第 38619 幀（約 1544.76 秒）。",
+  "need_input": false,
+  "sources": [
+    {
+      "tool": "tkg_query",
+      "result": "{\"first_cooccurrence\":{\"frame\":38619,\"timestamp_secs\":1544.76}}"
+    }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `conversation_id` | string | 後續對話需要傳入此 ID |
+| `answer` | string | Agent 的自然語言回答（或反問） |
+| `need_input` | boolean | `true` 表示 agent 需要更多資訊才能回答 |
+| `suggestions` | string[] | 建議用戶提供的線索（當 `need_input=true`） |
+| `sources` | array | 引用的工具執行結果 |
+
+### Conversation Flow
+
+```
+Round 1: POST /agents/search { query: "我想看男女主角同框" }
+         → need_input: true, suggestions: ["片名", "演員", "年代"]
+         → answer: "請問是哪部電影？請提供更多線索"
+
+Round 2: POST /agents/search { query: "奧黛麗赫本", conversation_id: "..." }
+         → need_input: false
+         → answer: "找到 Charade (1963)，Audrey Hepburn 和 Cary Grant..."
+```
+
+### Available Tools
+
+Agent 內部使用 Gemma4 function calling 自動調用以下工具：
+
+| Tool | Description |
+|------|-------------|
+| `find_file` | 透過片名/演員/年份關鍵字搜尋影片，回傳 file_uuid + has_data 狀態 |
+| `list_files` | 列出近期註冊的影片 |
+| `tkg_query` | 查詢人物互動資料（7 種子類型：top_identities、first_cooccurrence、identity_details、mutual_gaze、interaction_network、identity_traces、file_info） |
+| `smart_search` | 文字內容 ILIKE 搜尋 chunk（可指定 file_uuid 限制範圍） |
+| `get_identity_detail` | 查詢單一身份的詳細資料（角色、TMDb 資訊） |
+| `get_file_info` | 查詢影片基本資訊（片長、解析度） |
+| `get_representative_frame` | 查詢影片最具代表性的 frame 資訊 |
+
+### Design Principles
+
+- **用戶不需要知道 file_uuid** — Agent 會自動用 `find_file` 搜尋或反問
+- **不推薦無資料的影片** — `has_data=false` 的影片不會被推薦給用戶
+- **多輪對話** — 透過 `conversation_id` 延續上下文，agent 會記得之前的交流
+- **並行工具呼叫** — Gemma4 可以一次呼叫多個工具再綜合回答
+
+### Model
+
+| Detail | Value |
+|--------|-------|
+| **LLM** | Gemma4 26B (Q5_K_M) |
+| **Engine** | llama.cpp at `localhost:8082` |
+| **Endpoint** | `/v1/chat/completions` (OpenAI-compatible) |
+| **Temperature** | 0.1 |
+| **Max rounds** | 5 (tool call iterations) |
+| **Conversation TTL** | 30 minutes |
 
 ---
-*Updated: 2026-05-19 12:49:24*
+*Updated: 2026-05-22*
diff --git a/docs_v1.0/doc_wasm/modules/12_agent.md b/docs_v1.0/doc_wasm/modules/12_agent.md
index 8793ad3..cdc5fe0 100644
--- a/docs_v1.0/doc_wasm/modules/12_agent.md
+++ b/docs_v1.0/doc_wasm/modules/12_agent.md
@@ -116,6 +116,96 @@ Get status of the 5W1H agent pipeline for a file.
 | **Dimension** | 768 |
 | **Used by** | `parent_chunk_5w1h.py --embed`, story, 5W1H, search |
 
+---
+
+## POST /api/v1/agents/search
+
+Conversational search assistant. Uses Gemma4 function calling to automatically decide which tools to call based on the user's natural language query. Supports multi-turn conversation.
+
+### Request
+
+```json
+{
+  "query": "Audrey Hepburn 和 Cary Grant 第一次同框在哪個 frame？",
+  "conversation_id": null,
+  "file_uuid": null
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `query` | string | ✅ | 自然語言查詢 |
+| `conversation_id` | string | ❌ | 延續對話時傳入；新對話不傳 |
+| `file_uuid` | string | ❌ | Portal 有選中檔案時可指定 |
+
+### Response
+
+```json
+{
+  "success": true,
+  "conversation_id": "conv_abc123",
+  "answer": "在 Charade (1963) 中，Audrey Hepburn 與 Cary Grant 第一次同框在第 38619 幀（約 1544.76 秒）。",
+  "need_input": false,
+  "sources": [
+    {
+      "tool": "tkg_query",
+      "result": "{\"first_cooccurrence\":{\"frame\":38619,\"timestamp_secs\":1544.76}}"
+    }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `conversation_id` | string | 後續對話需要傳入此 ID |
+| `answer` | string | Agent 的自然語言回答（或反問） |
+| `need_input` | boolean | `true` 表示 agent 需要更多資訊才能回答 |
+| `suggestions` | string[] | 建議用戶提供的線索（當 `need_input=true`） |
+| `sources` | array | 引用的工具執行結果 |
+
+### Conversation Flow
+
+```
+Round 1: POST /agents/search { query: "我想看男女主角同框" }
+         → need_input: true, suggestions: ["片名", "演員", "年代"]
+         → answer: "請問是哪部電影？請提供更多線索"
+
+Round 2: POST /agents/search { query: "奧黛麗赫本", conversation_id: "..." }
+         → need_input: false
+         → answer: "找到 Charade (1963)，Audrey Hepburn 和 Cary Grant..."
+```
+
+### Available Tools
+
+Agent 內部使用 Gemma4 function calling 自動調用以下工具：
+
+| Tool | Description |
+|------|-------------|
+| `find_file` | 透過片名/演員/年份關鍵字搜尋影片，回傳 file_uuid + has_data 狀態 |
+| `list_files` | 列出近期註冊的影片 |
+| `tkg_query` | 查詢人物互動資料（7 種子類型：top_identities、first_cooccurrence、identity_details、mutual_gaze、interaction_network、identity_traces、file_info） |
+| `smart_search` | 文字內容 ILIKE 搜尋 chunk（可指定 file_uuid 限制範圍） |
+| `get_identity_detail` | 查詢單一身份的詳細資料（角色、TMDb 資訊） |
+| `get_file_info` | 查詢影片基本資訊（片長、解析度） |
+| `get_representative_frame` | 查詢影片最具代表性的 frame 資訊 |
+
+### Design Principles
+
+- **用戶不需要知道 file_uuid** — Agent 會自動用 `find_file` 搜尋或反問
+- **不推薦無資料的影片** — `has_data=false` 的影片不會被推薦給用戶
+- **多輪對話** — 透過 `conversation_id` 延續上下文，agent 會記得之前的交流
+- **並行工具呼叫** — Gemma4 可以一次呼叫多個工具再綜合回答
+
+### Model
+
+| Detail | Value |
+|--------|-------|
+| **LLM** | Gemma4 26B (Q5_K_M) |
+| **Engine** | llama.cpp at `localhost:8082` |
+| **Endpoint** | `/v1/chat/completions` (OpenAI-compatible) |
+| **Temperature** | 0.1 |
+| **Max rounds** | 5 (tool call iterations) |
+| **Conversation TTL** | 30 minutes |
 
 ---
-*Updated: 2026-05-19 12:49:24*
+*Updated: 2026-05-22*