momentry_core/docs/RELEASE_PHASES.md

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：

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（高難度，需資料或新模型）