# Momentry Model — 分階段交付

## 核心架構

```
Pipeline (training)
  │  每個 processor 產出 .json
  │  Rule 1/3 Ingestion → chunks + embeddings
  ▼
momentry model for {video}      ← 每部影片 = 一個 model
  │  release/phase1/latest/
  │  release/phase2/latest/
  ▼
momentry core (inference engine)  ← Rust API server
  │  momentry_playground (dev)
  │  momentry (production)
  ▼
Search / Query / Identity APIs
```

- **Pipeline** = training phase：影片 → processor output → chunks → embeddings
- **Model** = 每部影片的產出 package（output_json + chunks + vectors）
- **Engine** = momentry core，吃 model 提供 API（search, trace, identity）

每個影片可有多個 model 版本，命名保留升級空間：

| Model 版本 | Qdrant Collection | 內容 | 觸發時機 |
|-----------|------------------|------|---------|
| `{uuid}_v1` | `momentry_dev_v1` | sentence chunk embedding（base） | ASR + ASRX + Rule 1 完成 |
| `{uuid}_v2` | `momentry_dev_v2` | 完整 pipeline + 5W1H | 全部完成 |
| `{uuid}_v3` | `momentry_dev_v3` | object identity + custom detector | v2 + object instance matching 完成 |

各版本共存不覆蓋。

## 階段劃分

### Phase 1：Sentence Chunk Embedding（base model）

**觸發時機**: ASR + ASRX 完成 + Rule 1 Ingestion + vectorize 完成

**交付內容**:
- `{uuid}.asr.json`
- `{uuid}.asrx.json`
- chunks（chunk_type = 'sentence'）
- chunk_vectors（sentence embedding）

**用途**: 終端使用者可進行語意搜尋

### Phase 2：完整 Pipeline（v2 model）

**觸發時機**: 全部 processor 完成 + Rule 3 Ingestion + 5W1H Agent

**交付內容**:
- Phase 1 全部內容
- 所有 `{uuid}.*.json`（cut, yolo, face, pose, ocr, ...）
- chunks（chunk_type = 'cut', 'visual', 'trace', 'story'）
- chunk_vectors（summary embedding）
- identities / identity_bindings / face_detections

**用途**: 完整搜尋 + 摘要 + 人物識別

---

## Worker Pipeline

```
ASR 完成 → ASRX 完成
  ↓
Rule 1 Ingestion (sentence chunks)
  ↓
vectorize_chunks (sentence embedding)
  ↓
📦 Phase 1 release  ───→ release/phase1/latest/  (base model)
  ↓
其他 processors 繼續 (yolo, face, pose, ocr, ...)
  ↓
Rule 3 Ingestion + 5W1H Agent
  ↓
📦 Phase 2 release  ───→ release/phase2/latest/  (full model)
```

## 產出目錄結構

```
release/
├── phase1/
│   ├── {version}_{timestamp}/
│   │   ├── output_json/      ← 所有已完成的 .json
│   │   ├── chunks.csv        ← sentence chunks
│   │   ├── vectors.csv       ← sentence embeddings
│   │   ├── schema.sql        ← chunks table DDL
│   │   └── RELEASE_INFO.txt
│   └── latest → {version}_{timestamp}
│
└── phase2/
    ├── {version}_{timestamp}/
    │   ├── output_json/      ← 所有 .json
    │   ├── chunks.csv        ← 所有 chunks
    │   ├── vectors.csv       ← 所有 embeddings
    │   ├── identities.csv    ← 人物身分
    │   ├── schema.sql        ← 完整 schema
    │   └── RELEASE_INFO.txt
    └── latest → {version}_{timestamp}
```

## momentry model vs momentry core

| | momentry model | momentry core |
|---|---|---|
| 類比 | 訓練好的 weights | inference engine |
| 內容 | `.json` + chunks + vectors | Rust binary |
| 生命週期 | 每部影片產出一個 | 一個 binary 服務所有影片 |
| 版本 | `{uuid}_v1`（base） / `{uuid}_v2` / `{uuid}_v3` | `momentry_playground` / `momentry` |
| 交付對象 | 終端使用者 | 部署工程師 |

---

## Wiki 機制：每個 model 都可被調整

每個 momentry model（`{uuid}_v1` / `v2` / `v3`）不只是唯讀的產出，而是可透過 wiki 機制持續改善。

### 與傳統 RAG 的區別

| | 傳統 RAG | momentry wiki |
|---|---|---|
| 知識儲存 | vector DB（ephemeral） | model package（permanent） |
| 修正方式 | query 時 LLM 決定是否採用 | 使用者/Agent 直接編輯 |
| 修正持久性 | ❌ 下次 query 就消失 | ✅ 寫入 model，版本化保存 |
| 模型改進 | 無（僅改變 prompt） | 下次 version bump 時合併為 ground truth |
| 協作方式 | 單向（retrieve → generate） | 雙向（編輯 → 合併 → 改進） |
| 離線可用 | ❌ 需 vector DB + LLM | ✅ 離線查閱 wiki 目錄 |

**momentry wiki 不是 RAG 的替代品，而是 model 的生命週期管理機制。**

### 概念

```
momentry model (release package)
  ├── output_json/          ← 唯讀，processor 產出
  ├── chunks.csv            ← 唯讀，ingestion 產出
  ├── vectors.csv           ← 唯讀，embedding 產出
  └── wiki/                 ← 可編輯，使用者貢獻知識
        ├── identities.json   ← "trace 5 = Audrey Hepburn"
        ├── objects.json      ← "object 42 = 郵票 #1"
        ├── corrections.json  ← "ASR 'Hello' → 'Halo'"
        └── changelog.json    ← 編輯歷史
```

### 資料流向

```
使用者/Agent 編輯 wiki
        ↓
  DB wiki_entries + wiki_revisions 寫入
        ↓
  下次 release 打包時 merge 進 model
        ↓
  TKG label 更新 (tkg_nodes.label)
        ↓
  新版 model version bump
```

### 與 TKG 的關係

wiki 的 identity 和 object 標註會回寫到 TKG node label：
```
(face_trace:5) label="Audrey Hepburn"     ← wiki 編輯
(object_instance:42) label="郵票 #1"       ← wiki 編輯
```

這些編輯累積後，可做為下一版 model training 的 ground truth。

### 實作方向

**DB 層** — 新 table `wiki_entries` + `wiki_revisions`：
```sql
wiki_entries (target_type, target_id, title, body, summary, status, version, file_uuid)
wiki_revisions (entry_id, version, title, body, summary, change_summary, edited_by)
```

**API 層** — CRUD + 版本歷史：
```
GET    /api/v1/wiki/{target_type}/{target_id}
PUT    /api/v1/wiki/{target_type}/{target_id}
GET    /api/v1/wiki/{target_type}/{target_id}/revisions
POST   /api/v1/wiki/search
```

**打包層** — `release_pack.py` 加入 wiki 匯出，與 model 共存

---

## Phase 3：Object Identity（v3 model）

### 目標

從影片中提取關鍵物體（郵票、手槍、信封、放大鏡...），對同類物體做 instance-level 的跨畫面追蹤與辨識，達到類似 face trace 的效果 — 不只是 detect class，還能區分「這一張郵票」vs「那一張郵票」。

### 現狀問題

1. **COCO 80 類不包含關鍵物體** — 郵票、手槍、信封、放大鏡等不在 COCO 資料集中
2. **YOLOv5nano 偵測率低** — 即使是 COCO 類別（knife, cell phone）在 nano 模型上 recall 不足
3. **無 object instance matching** — 目前只有 frame-level detection，沒有跨 frame 的物體追蹤

### 技術方向

```
YOLOv8m/OWL-ViT → 改善 detection coverage
        ↓
 Object Tracker (IoU + embedding，類似 face tracker)
        ↓
 object_trace → TKG CO_OCCURS_WITH edges
        ↓
 object identity → 同物體跨場景辨識
```

| 方向 | 方法 | 效果 |
|------|------|------|
| Model upgrade | `yolov5nu` → `yolov8s.pt` / `yolov8m.pt` | COCO recall 提升 |
| Custom fine-tune | 收集 stamps/guns 資料 fine-tune YOLO | 可偵測非 COCO 物件 |
| Zero-shot | OWL-ViT / Grounding DINO by text prompt | 不用 training，但速度慢 |
| Object trace | IoU + embedding 跨 frame 匹配 | instance-level 追蹤 |
| Object identity | clustering 跨場景辨識同一物體 | 可在全片搜尋「這把槍」 |

### 與 TKG 整合

```
face_trace -[:CO_OCCURS_WITH]-> object_instance:5  (這把槍)
face_trace -[:CO_OCCURS_WITH]-> object_instance:42 (這張郵票)

查詢: "Audrey Hepburn 拿這把槍的畫面"
→ face_trace:5 -[:SPEAKS_AS]-> SPEAKER_0
→ face_trace:5 -[:CO_OCCURS_WITH]-> object_instance:5
```

### 交付順序

1. YOLO model upgrade（低難度，立即見效）
2. Object tracker（中難度，參考 face tracker 實作）
3. Custom fine-tune / zero-shot（高難度，需資料或新模型）