Compare commits
17 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 accusys
|
83ae05014f | ||
|
accusys
|
171c36acce | ||
|
accusys
|
02c63892b7 | ||
|
accusys
|
93a9f8c349 | ||
|
accusys
|
89fbfd6ad9 | ||
|
accusys
|
3edaf01f6c | ||
|
accusys
|
786381ac67 | ||
|
accusys
|
2d787b7806 | ||
|
accusys
|
fe24906791 | ||
|
accusys
|
1d1c60366e | ||
|
accusys
|
bfc4317b88 | ||
|
accusys
|
26f73ab620 | ||
|
accusys
|
47b9c2f750 | ||
|
accusys
|
e66b9501bd | ||
|
accusys
|
9bbfaa1d06 | ||
|
accusys
|
ea2bbb9fd9 | ||
|
accusys
|
de14bd6afa |
@@ -0,0 +1,40 @@
|
||||
# Database Configuration
|
||||
DATABASE_URL=postgres://accusys@localhost:5432/momentry
|
||||
|
||||
# Redis
|
||||
# Format: redis://[username][:password]@host:port
|
||||
# Users: default (with password), accusys (custom user with password)
|
||||
REDIS_URL=redis://accusys:accusys@localhost:6379
|
||||
|
||||
# MongoDB
|
||||
MONGODB_URL=mongodb://accusys:Test3200Test3200@localhost:27017/admin
|
||||
MONGODB_DATABASE=momentry
|
||||
|
||||
# Qdrant Vector Database
|
||||
QDRANT_URL=http://localhost:6333
|
||||
QDRANT_API_KEY=Test3200Test3200Test3200
|
||||
QDRANT_COLLECTION=chunks_v3
|
||||
|
||||
# Gitea
|
||||
GITEA_URL=http://localhost:3000
|
||||
|
||||
# API Server (Production)
|
||||
MOMENTRY_SERVER_PORT=3002
|
||||
MOMENTRY_REDIS_PREFIX=momentry:
|
||||
API_HOST=127.0.0.1
|
||||
API_PORT=3002
|
||||
|
||||
# Worker Configuration (Production)
|
||||
MOMENTRY_WORKER_ENABLED=true
|
||||
MOMENTRY_MAX_CONCURRENT=2
|
||||
MOMENTRY_POLL_INTERVAL=5
|
||||
|
||||
# Watch Directories (comma separated)
|
||||
WATCH_DIRECTORIES=~/Videos,~/momentry_core_project/test_video
|
||||
|
||||
# Ollama (for Mistral 7B LLM)
|
||||
OLLAMA_HOST=http://localhost:11434
|
||||
|
||||
# Model Paths
|
||||
# EMBEDDING_MODEL_PATH=./models/comic-embed-text
|
||||
# LLM_MODEL_PATH=./models/mistral-7b
|
||||
+18
-61
@@ -8,41 +8,39 @@
|
||||
MOMENTRY_SERVER_PORT=3003
|
||||
MOMENTRY_REDIS_PREFIX=momentry_dev:
|
||||
|
||||
# Worker Configuration (enabled for development)
|
||||
MOMENTRY_WORKER_ENABLED=true
|
||||
MOMENTRY_MAX_CONCURRENT=6
|
||||
# Worker Configuration (disabled by default for development)
|
||||
MOMENTRY_WORKER_ENABLED=false
|
||||
MOMENTRY_MAX_CONCURRENT=1
|
||||
MOMENTRY_POLL_INTERVAL=10
|
||||
MOMENTRY_WORKER_BATCH_SIZE=5
|
||||
|
||||
# Database (PostgreSQL) - Schema isolation
|
||||
# Database (same as production, but could use separate dev database)
|
||||
DATABASE_URL=postgres://accusys@localhost:5432/momentry
|
||||
DATABASE_SCHEMA=dev
|
||||
|
||||
# MongoDB - Database isolation
|
||||
MONGODB_URL=mongodb://localhost:27017
|
||||
MONGODB_DATABASE=momentry_dev
|
||||
# MongoDB
|
||||
MONGODB_URL=mongodb://accusys:Test3200Test3200@localhost:27017/admin
|
||||
MONGODB_DATABASE=momentry
|
||||
|
||||
# Redis (already isolated via prefix)
|
||||
REDIS_URL=redis://127.0.0.1:6379
|
||||
# REDIS_PASSWORD not set - Redis has no password configured
|
||||
# Redis
|
||||
REDIS_URL=redis://:accusys@localhost:6379
|
||||
REDIS_PASSWORD=accusys
|
||||
|
||||
# Qdrant Vector Database - Collection isolation
|
||||
# Qdrant Vector Database (same as production)
|
||||
QDRANT_URL=http://localhost:6333
|
||||
QDRANT_API_KEY=Test3200Test3200Test3200
|
||||
QDRANT_COLLECTION=momentry_dev_rule1_v2
|
||||
QDRANT_COLLECTION=chunks_v3
|
||||
|
||||
# Paths
|
||||
MOMENTRY_OUTPUT_DIR=/Users/accusys/momentry/output_dev
|
||||
MOMENTRY_BACKUP_DIR=/Users/accusys/momentry/backup/momentry_dev
|
||||
MOMENTRY_SFTP_ROOT=/Users/accusys/momentry/var/sftpgo/data/demo/
|
||||
|
||||
# Python (for processing scripts)
|
||||
MOMENTRY_PYTHON_PATH=/Users/accusys/momentry_core/venv/bin/python
|
||||
MOMENTRY_SCRIPTS_DIR=/Users/accusys/momentry_core/scripts
|
||||
MOMENTRY_PYTHON_PATH=/opt/homebrew/bin/python3.11
|
||||
MOMENTRY_SCRIPTS_DIR=/Users/accusys/momentry_core_0.1/scripts
|
||||
|
||||
# Logging
|
||||
RUST_LOG=info
|
||||
MOMENTRY_LOG_LEVEL=info
|
||||
RUST_LOG=debug
|
||||
MOMENTRY_LOG_LEVEL=debug
|
||||
|
||||
# Media
|
||||
MOMENTRY_MEDIA_BASE_URL=https://wp.momentry.ddns.net
|
||||
@@ -53,51 +51,10 @@ MOMENTRY_CUT_TIMEOUT=3600
|
||||
MOMENTRY_DEFAULT_TIMEOUT=7200
|
||||
|
||||
# Cache Settings
|
||||
MONGODB_CACHE_ENABLED=false
|
||||
MONGODB_CACHE_ENABLED=true
|
||||
MONGODB_CACHE_TTL_VIDEOS=300
|
||||
MONGODB_CACHE_TTL_SEARCH=300
|
||||
MONGODB_CACHE_TTL_HYBRID_SEARCH=600
|
||||
MONGODB_CACHE_TTL_VIDEO_META=3600
|
||||
REDIS_CACHE_TTL_HEALTH=30
|
||||
REDIS_CACHE_TTL_VIDEO_META=3600
|
||||
# 同義詞配置文件（可選）
|
||||
# 取消註釋並設置為您的同義詞JSON檔案路徑以啟用同義詞擴展
|
||||
# MOMENTRY_SYNONYM_FILE=/Users/accusys/momentry_core_0.1/docs/examples/custom_synonyms.json
|
||||
#
|
||||
# 多個同義詞檔案（逗號分隔），會覆蓋 MOMENTRY_SYNONYM_FILE
|
||||
# MOMENTRY_SYNONYM_FILES=/path/to/first.json,/path/to/second.json
|
||||
#
|
||||
# 示例檔案：docs/examples/custom_synonyms.json
|
||||
|
||||
# TMDb Integration (probe phase - auto-create identities from movie metadata)
|
||||
TMDB_API_KEY=e9cde52197f6f8df4d9db99da93db1fb
|
||||
MOMENTRY_TMDB_PROBE_ENABLED=true
|
||||
# LLM for 5W1H summary (points to M5 Gemma4)
|
||||
MOMENTRY_LLM_SUMMARY_URL=http://127.0.0.1:8000/v1/chat/completions
|
||||
MOMENTRY_LLM_SUMMARY_MODEL=gemma-4-E4B
|
||||
MOMENTRY_LLM_SUMMARY_ENABLED=true
|
||||
|
||||
# LLM Chat (E4B on port 8000)
|
||||
MOMENTRY_LLM_CHAT_URL=http://127.0.0.1:8000/v1/chat/completions
|
||||
MOMENTRY_LLM_CHAT_MODEL=gemma-4-E4B
|
||||
|
||||
# LLM Vision (E4B on port 8000)
|
||||
MOMENTRY_LLM_VISION_URL=http://127.0.0.1:8000/v1/chat/completions
|
||||
MOMENTRY_LLM_VISION_MODEL=gemma-4-E4B
|
||||
|
||||
# Embedding (ANE CoreML server)
|
||||
MOMENTRY_EMBED_URL=http://localhost:11436
|
||||
|
||||
# === Binary & Data Paths (for start_momentry.sh) ===
|
||||
MOMENTRY_LOG_DIR=/Users/accusys/momentry/logs
|
||||
MOMENTRY_PG_BIN_DIR=/Users/accusys/pgsql/18.3/bin
|
||||
MOMENTRY_PG_DATA_DIR=/Users/accusys/pgsql/data
|
||||
MOMENTRY_QDRANT_BIN=/Users/accusys/.cargo/bin/qdrant
|
||||
MOMENTRY_QDRANT_STORAGE_DIR=/Users/accusys/momentry/qdrant_storage
|
||||
MOMENTRY_LLAMACPP_BIN=/Users/accusys/llama/bin/llama-server
|
||||
MOMENTRY_LLM_A4B_MODEL_PATH=/Users/accusys/models/google_gemma-4-26B-A4B-it-Q5_K_M.gguf
|
||||
MOMENTRY_LLM_A4B_MMPROJ_PATH=/Users/accusys/models/gemma-4-26B-A4B-it.mmproj-f16.gguf
|
||||
MOMENTRY_LLM_E4B_MODEL_PATH=/Users/accusys/models/gemma-4-E4B-it-Q4_K_M.gguf
|
||||
MOMENTRY_LLM_E4B_MMPROJ_PATH=/Users/accusys/models/mmproj-gemma-4-E4B-it-BF16.gguf
|
||||
MOMENTRY_OLLAMA_BIN=/Users/accusys/bin/ollama
|
||||
MOMENTRY_PLAYGROUND_BIN=target/debug/momentry_playground
|
||||
REDIS_CACHE_TTL_VIDEO_META=3600
|
||||
+58
-51
@@ -1,63 +1,70 @@
|
||||
# Momentry Core Environment Configuration
|
||||
# Copy this file to .env and fill in your values
|
||||
# DO NOT commit .env to version control
|
||||
# Momentry Core Configuration Template
|
||||
# Copy this file to .env and customize for your environment
|
||||
# DO NOT commit .env with real credentials to version control
|
||||
|
||||
# === Database ===
|
||||
DATABASE_URL=postgres://accusys@localhost:5432/momentry
|
||||
DATABASE_SCHEMA=dev
|
||||
# ===========================================
|
||||
# Database Configuration
|
||||
# ===========================================
|
||||
DATABASE_URL=postgres://user:password@localhost:5432/momentry
|
||||
|
||||
# === MongoDB ===
|
||||
MONGODB_URL=mongodb://localhost:27017
|
||||
# ===========================================
|
||||
# Redis Configuration
|
||||
# ===========================================
|
||||
REDIS_URL=redis://user:password@localhost:6379
|
||||
REDIS_PASSWORD=your_redis_password
|
||||
|
||||
# ===========================================
|
||||
# MongoDB Configuration
|
||||
# ===========================================
|
||||
MONGODB_URL=mongodb://user:password@localhost:27017/admin
|
||||
MONGODB_DATABASE=momentry
|
||||
MONGODB_CACHE_ENABLED=true
|
||||
|
||||
# === Redis ===
|
||||
REDIS_URL=redis://:accusys@localhost:6379
|
||||
REDIS_PASSWORD=accusys
|
||||
MOMENTRY_REDIS_PREFIX=momentry_dev:
|
||||
# ===========================================
|
||||
# Qdrant Configuration
|
||||
# ===========================================
|
||||
QDRANT_URL=http://localhost:6333
|
||||
QDRANT_API_KEY=your_qdrant_api_key
|
||||
QDRANT_COLLECTION=chunks_v3
|
||||
|
||||
# === Qdrant ===
|
||||
QDRANT_COLLECTION=momentry_rule1
|
||||
# ===========================================
|
||||
# API Server Configuration
|
||||
# ===========================================
|
||||
API_HOST=127.0.0.1
|
||||
API_PORT=3000
|
||||
|
||||
# === API Keys ===
|
||||
MOMENTRY_API_KEY=muser_your_key_here
|
||||
MOMENTRY_DEMO_API_KEY=muser_your_demo_key_here
|
||||
JWT_SECRET=your_jwt_secret_here_change_in_production
|
||||
SFTPGO_BASE_URL=http://127.0.0.1:8080
|
||||
|
||||
TMDB_API_KEY=your_tmdb_api_key_here
|
||||
|
||||
# === LLM ===
|
||||
MOMENTRY_LLM_SUMMARY_URL=http://127.0.0.1:8082/v1/chat/completions
|
||||
MOMENTRY_LLM_SUMMARY_MODEL=google_gemma-4-26B-A4B-it-Q5_K_M.gguf
|
||||
MOMENTRY_LLM_SUMMARY_TIMEOUT=120
|
||||
|
||||
# LLM Chat (A4B)
|
||||
MOMENTRY_LLM_CHAT_URL=http://127.0.0.1:8082/v1/chat/completions
|
||||
MOMENTRY_LLM_CHAT_MODEL=google_gemma-4-26B-A4B-it-Q5_K_M.gguf
|
||||
MOMENTRY_LLM_CHAT_TIMEOUT=120
|
||||
|
||||
# LLM Vision (E4B)
|
||||
MOMENTRY_LLM_VISION_URL=http://127.0.0.1:8083/v1/chat/completions
|
||||
MOMENTRY_LLM_VISION_MODEL=gemma-4-E4B-it-Q4_K_M.gguf
|
||||
MOMENTRY_LLM_VISION_TIMEOUT=120
|
||||
|
||||
# === Paths ===
|
||||
MOMENTRY_OUTPUT_DIR=/Users/accusys/momentry/output_dev
|
||||
MOMENTRY_BACKUP_DIR=/Users/accusys/momentry/backup
|
||||
MOMENTRY_SCRIPTS_DIR=/Users/accusys/momentry_core_0.1/scripts
|
||||
# ===========================================
|
||||
# Directory Paths
|
||||
# ===========================================
|
||||
MOMENTRY_OUTPUT_DIR=/path/to/output
|
||||
MOMENTRY_BACKUP_DIR=/path/to/backup
|
||||
MOMENTRY_SCRIPTS_DIR=/path/to/momentry_core/scripts
|
||||
MOMENTRY_PYTHON_PATH=/opt/homebrew/bin/python3.11
|
||||
MOMENTRY_FFMPEG=/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg
|
||||
MOMENTRY_MEDIA_BASE_URL=
|
||||
|
||||
# === Encryption ===
|
||||
AUDIT_ENCRYPTION_KEY= # 32 bytes hex (64 hex chars)
|
||||
|
||||
# === Processor Timeouts (seconds) ===
|
||||
# ===========================================
|
||||
# Processor Timeouts (seconds)
|
||||
# ===========================================
|
||||
MOMENTRY_ASR_TIMEOUT=3600
|
||||
MOMENTRY_CUT_TIMEOUT=3600
|
||||
MOMENTRY_DEFAULT_TIMEOUT=7200
|
||||
|
||||
# === Server ===
|
||||
MOMENTRY_SERVER_PORT=3003
|
||||
MOMENTRY_LOG_LEVEL=info
|
||||
# ===========================================
|
||||
# Watch Directories (comma separated)
|
||||
# ===========================================
|
||||
WATCH_DIRECTORIES=~/Videos,~/Downloads
|
||||
|
||||
# ===========================================
|
||||
# Logging
|
||||
# ===========================================
|
||||
RUST_LOG=info
|
||||
# Options: trace, debug, info, warn, error
|
||||
|
||||
# ===========================================
|
||||
# Ollama (for LLM integration)
|
||||
# ===========================================
|
||||
OLLAMA_HOST=http://localhost:11434
|
||||
|
||||
# ===========================================
|
||||
# Model Paths
|
||||
# ===========================================
|
||||
# EMBEDDING_MODEL_PATH=./models/embedding
|
||||
# LLM_MODEL_PATH=./models/llm
|
||||
|
||||
+37
-46
@@ -1,49 +1,40 @@
|
||||
target/
|
||||
.DS_Store
|
||||
# Environment - Local configs (NEVER commit these)
|
||||
.env
|
||||
.env.development
|
||||
*.gguf
|
||||
*.mlpackage
|
||||
*.pt
|
||||
*.pth
|
||||
*.bin
|
||||
*.onnx
|
||||
*.zip
|
||||
*.tar.gz
|
||||
venv/
|
||||
__pycache__/
|
||||
node_modules/
|
||||
*.log
|
||||
/tmp/
|
||||
*.diff
|
||||
*.bundle
|
||||
*.probe.json
|
||||
*.cut.json
|
||||
.qdrant-initialized
|
||||
dump.rdb
|
||||
fix55.js
|
||||
checksums.sha256
|
||||
.env.local
|
||||
.env.*.local
|
||||
|
||||
scripts/swift_processors/.build/
|
||||
.opencode/
|
||||
.vscode/
|
||||
backups/
|
||||
logs/
|
||||
output/
|
||||
models/
|
||||
data/
|
||||
storage/
|
||||
# Build artifacts
|
||||
target/
|
||||
venv/
|
||||
|
||||
# Generated files
|
||||
thumbnails/
|
||||
services/
|
||||
model_checkpoints/
|
||||
release/delivery/
|
||||
release/system/
|
||||
release/phase*/
|
||||
release/dev_*.sql
|
||||
release/migrate_*.sql
|
||||
release/files/
|
||||
package-lock.json
|
||||
package.json
|
||||
portal/dist/
|
||||
portal/src-tauri/icons/
|
||||
momentry_runtime/logs/
|
||||
*.asr.json
|
||||
*.probe.json
|
||||
test_asr.json
|
||||
|
||||
# Local output (machine learning results)
|
||||
output/
|
||||
*.pt
|
||||
|
||||
# Cache
|
||||
.ruff_cache/
|
||||
|
||||
# OS files
|
||||
.DS_Store
|
||||
.Spotlight-V100
|
||||
.Trashes
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
|
||||
# SSH keys (NEVER commit)
|
||||
id_*
|
||||
!id_*.pub
|
||||
|
||||
# IDE and editor
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
@@ -1,21 +0,0 @@
|
||||
{
|
||||
"default": true,
|
||||
"MD003": false,
|
||||
"MD009": false,
|
||||
"MD010": false,
|
||||
"MD013": false,
|
||||
"MD022": false,
|
||||
"MD024": false,
|
||||
"MD025": false,
|
||||
"MD031": false,
|
||||
"MD032": false,
|
||||
"MD033": false,
|
||||
"MD034": false,
|
||||
"MD036": false,
|
||||
"MD040": false,
|
||||
"MD046": false,
|
||||
"MD055": false,
|
||||
"MD056": false,
|
||||
"MD058": false,
|
||||
"MD060": false
|
||||
}
|
||||
@@ -1,21 +0,0 @@
|
||||
{
|
||||
"default": true,
|
||||
"MD003": false,
|
||||
"MD009": false,
|
||||
"MD010": false,
|
||||
"MD013": false,
|
||||
"MD022": false,
|
||||
"MD024": false,
|
||||
"MD025": false,
|
||||
"MD031": false,
|
||||
"MD032": false,
|
||||
"MD033": false,
|
||||
"MD034": false,
|
||||
"MD036": false,
|
||||
"MD040": false,
|
||||
"MD046": false,
|
||||
"MD055": false,
|
||||
"MD056": false,
|
||||
"MD058": false,
|
||||
"MD060": false
|
||||
}
|
||||
-15
@@ -1,15 +0,0 @@
|
||||
{
|
||||
"db_name": "PostgreSQL",
|
||||
"query": "UPDATE dev.videos SET processing_status = $1 WHERE uuid = $2",
|
||||
"describe": {
|
||||
"columns": [],
|
||||
"parameters": {
|
||||
"Left": [
|
||||
"Jsonb",
|
||||
"Text"
|
||||
]
|
||||
},
|
||||
"nullable": []
|
||||
},
|
||||
"hash": "2d61eacd106ad5144c99a85c84f070924af9b29103a507e115674d1b14b77181"
|
||||
}
|
||||
-14
@@ -1,14 +0,0 @@
|
||||
{
|
||||
"db_name": "PostgreSQL",
|
||||
"query": "UPDATE dev.jobs SET status = 'COMPLETED', processed_frames = total_frames, updated_at = NOW() WHERE id = $1",
|
||||
"describe": {
|
||||
"columns": [],
|
||||
"parameters": {
|
||||
"Left": [
|
||||
"Uuid"
|
||||
]
|
||||
},
|
||||
"nullable": []
|
||||
},
|
||||
"hash": "345d912734b063a7b30d52c066045553964d0a55453a7e26a4d8b8d758be3857"
|
||||
}
|
||||
-15
@@ -1,15 +0,0 @@
|
||||
{
|
||||
"db_name": "PostgreSQL",
|
||||
"query": "UPDATE dev.jobs SET status = 'FAILED', error_message = $2, updated_at = NOW() WHERE id = $1",
|
||||
"describe": {
|
||||
"columns": [],
|
||||
"parameters": {
|
||||
"Left": [
|
||||
"Uuid",
|
||||
"Text"
|
||||
]
|
||||
},
|
||||
"nullable": []
|
||||
},
|
||||
"hash": "60cc008705cfea3a4532b9496db8f6ed0e3023436660bdf8ee81fe78fe270971"
|
||||
}
|
||||
@@ -2,193 +2,12 @@
|
||||
|
||||
Rust-based digital asset management system with video analysis and RAG capabilities.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ CRITICAL: 開發隔離原則
|
||||
|
||||
### 絕對禁止事項
|
||||
- **絕對不可修改 `/Users/accusys/wordpress/` 目錄下的任何檔案**
|
||||
- **絕對不可修改 n8n 工作流或設定**
|
||||
- **絕對不可修改 WordPress 或 n8n 的資料庫 table**
|
||||
- **除非是 release 作業，絕對不可動 port 3002 (production)**
|
||||
- **🔴 DELETE / REMOVE / DROP / CLEAR 任何資料前必須先問使用者「要刪嗎？」獲得明確同意後才能執行**
|
||||
- **🔴 Qdrant collection 刪除、DB truncate、檔案刪除、資料清空 — 一律要先問**
|
||||
- **🔴 不確定是否該刪 → 先問，不要自己決定**
|
||||
- **🔴 改變議題前必須先存檔紀錄**：使用 `todowrite` 工具或建立紀錄文件（如 `docs_v1.0/M4_workspace/YYYY-MM-DD_topic_handoff.md`），確保上下文不丟失
|
||||
|
||||
### 開發範圍界定
|
||||
| 範圍 | 狀態 | 說明 |
|
||||
|------|------|------|
|
||||
| `momentry_core_0.1/` | ✅ **可開發** | Momentry Core 主要開發目錄 |
|
||||
| `momentry_core_0.1/portal/` | ✅ **可開發** | Tauri Portal 前端 |
|
||||
| `momentry_core_0.1/src/` | ✅ **可開發** | Rust 後端程式碼 |
|
||||
| `/Users/accusys/wordpress/` | ❌ **禁止修改** | WordPress/Marcom 團隊負責 |
|
||||
| n8n 工作流 | ❌ **禁止修改** | 自動化流程，與 dev 無關 |
|
||||
| WordPress/n8n 資料庫 table | ❌ **禁止修改** | Marcom 團隊管理，與 dev 無關 |
|
||||
|
||||
### 開發環境
|
||||
| 服務 | Port | 用途 | 命令 |
|
||||
|------|------|------|------|
|
||||
| Playground | 3003 | **唯一開發環境** | `cargo run --bin momentry_playground -- server` |
|
||||
| Production | 3002 | ❌ 禁止修改 | `cargo run -- server` (僅 release 時) |
|
||||
| Portal (Tauri) | 1420 | 前端開發 | `npm run tauri dev` |
|
||||
|
||||
### 日誌與啟動
|
||||
| 服務 | 日誌路徑 | 啟動方式 |
|
||||
|------|----------|----------|
|
||||
| Production (3002) | `logs/momentry_3002.log` | `./run-server-3002.sh` |
|
||||
| Playground (3003) | `logs/momentry_3003.log` | `./run-server-3003.sh` |
|
||||
| Worker / 歷史 | `logs/nohup_worker_*.log` | 由 worker 自動產生 |
|
||||
|
||||
> **注意**: 所有伺服器日誌統一存放於專案內 `logs/` 目錄。
|
||||
> 啟動腳本會自動 kill 舊程序、重 build（若需要）、並將日誌導向 `logs/`。
|
||||
|
||||
## ⚠️ 交叉污染防制 (Cross-Contamination Prevention)
|
||||
|
||||
**每個執行前必須評估是否會汙染其他獨立作業。**
|
||||
|
||||
### Scope Isolation Matrix
|
||||
|
||||
| 執行內容 | 允許的 Scope | 禁止影響 | 檢查事項 |
|
||||
|----------|-------------|----------|----------|
|
||||
| M4 delivery binary | `target/release/momentry` | Playground (3003), Production (3002) | 確認舊 process 未被誤殺 |
|
||||
| Playground server | `localhost:3003`, `dev.*` schema | Production (3002), `public.*` schema | `DATABASE_SCHEMA=dev` |
|
||||
| Production deploy | `localhost:3002`, `public.*` schema | Playground (3003), `dev.*` schema | 先停 production，不影響 playground |
|
||||
| Git commit | 只包含意圖修改的檔案 | 無關的 untracked files | `git status` 確認 stage 內容正確 |
|
||||
| CI / packaged tests | 測試環境 | 正式資料 | 測試用 DB 不能連到 production |
|
||||
| Doc changes | 指定文件 | 其他文件、程式碼 | `git diff --stat` 檢查 scope |
|
||||
| SQL migration | 目標 schema | 其他 schema、無關 table | `WHERE` clause 要精準 |
|
||||
| `sed` / `grep` / mass edit | 目標檔案集 | 非目標檔案 | 先用 `grep -c` 確認只有目標檔案匹配 |
|
||||
|
||||
### Recent Violations / Near-Misses
|
||||
|
||||
| 事件 | 問題 | 防止方式 |
|
||||
|------|------|----------|
|
||||
| `sed` API doc 編號 | `sed -i '' 's/.../.../g'` 改到所有行 | 先 `grep -c` 確認匹配，`git diff` 再提交 |
|
||||
| 亂加 `/api/v1/register` route | 不必要的 API 別名，汙染路由表 | 角色切換：路由設計不該由實作方決定 |
|
||||
| `API_WORKSPACE/` vs `GUIDES/` vs `REFERENCE/` vs `DESIGN/` vs `OPERATIONS/` vs `INTEGRATIONS/` | 文件放到錯誤分類 | API 文件改在 API_WORKSPACE/modules/ 編輯，`make deploy` 生成到 GUIDES/ |
|
||||
| Build release binary in plan mode | 浪費時間，無意義 | 嚴格遵守 plan/build mode 規定 |
|
||||
|
||||
### ⛔ 嚴格測試隔離規則 (Strict Test Isolation)
|
||||
- **所有測試 (Test) 必須在 Dev (3003) 進行**。
|
||||
- **絕對禁止 (ABSOLUTELY FORBIDDEN)** 在任何測試指令、Demo 流程或 API 檢查中使用 `localhost:3002`。
|
||||
- 即使是「測試 Unregister」或「檢查版本」，若未明確標示為 "Production Deployment"，一律視為違規。
|
||||
- **預設行為**: 所有 curl, CLI, 或程式碼測試指令，預設 URL 必須為 `http://localhost:3003`。
|
||||
|
||||
### 違反後果
|
||||
- 修改 WordPress/n8n 可能影響 marcom 團隊工作與生產環境
|
||||
- 修改 WordPress/n8n 資料庫 table 可能破壞自動化流程與資料完整性
|
||||
- 修改 port 3002 可能中斷正在使用的服務 (這是非常嚴重的錯誤)
|
||||
- 所有 dev 測試必須在 playground (3003) 進行
|
||||
|
||||
---
|
||||
|
||||
## AI Coding Principles (Karpathy-Inspired)
|
||||
|
||||
Behavioral guidelines to reduce common LLM coding mistakes.
|
||||
Source: [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) (94K stars)
|
||||
|
||||
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
|
||||
|
||||
### 1. Think Before Coding
|
||||
|
||||
**Don't assume. Don't hide confusion. Surface tradeoffs.**
|
||||
|
||||
- State your assumptions explicitly. If uncertain, ask.
|
||||
- If multiple interpretations exist, present them - don't pick silently.
|
||||
- If a simpler approach exists, say so. Push back when warranted.
|
||||
- If something is unclear, stop. Name what's confusing. Ask.
|
||||
|
||||
### 2. Simplicity First
|
||||
|
||||
**Minimum code that solves the problem. Nothing speculative.**
|
||||
|
||||
- No features beyond what was asked.
|
||||
- No abstractions for single-use code.
|
||||
- No "flexibility" or "configurability" that wasn't requested.
|
||||
- No error handling for impossible scenarios.
|
||||
- If you write 200 lines and it could be 50, rewrite it.
|
||||
|
||||
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
|
||||
|
||||
### 3. Surgical Changes
|
||||
|
||||
**Touch only what you must. Clean up only your own mess.**
|
||||
|
||||
When editing existing code:
|
||||
- Don't "improve" adjacent code, comments, or formatting.
|
||||
- Don't refactor things that aren't broken.
|
||||
- Match existing style, even if you'd do it differently.
|
||||
- If you notice unrelated dead code, mention it - don't delete it.
|
||||
|
||||
When your changes create orphans:
|
||||
- Remove imports/variables/functions that YOUR changes made unused.
|
||||
- Don't remove pre-existing dead code unless asked.
|
||||
|
||||
The test: Every changed line should trace directly to the user's request.
|
||||
|
||||
### 4. Goal-Driven Execution
|
||||
|
||||
**Define success criteria. Loop until verified.**
|
||||
|
||||
Transform tasks into verifiable goals:
|
||||
- "Add validation" -> "Write tests for invalid inputs, then make them pass"
|
||||
- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
|
||||
- "Refactor X" -> "Ensure tests pass before and after"
|
||||
|
||||
For multi-step tasks, state a brief plan:
|
||||
```
|
||||
1. [Step] -> verify: [check]
|
||||
2. [Step] -> verify: [check]
|
||||
3. [Step] -> verify: [check]
|
||||
```
|
||||
|
||||
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
|
||||
|
||||
---
|
||||
|
||||
These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
|
||||
|
||||
---
|
||||
|
||||
## Terminology (V4.0)
|
||||
|
||||
| Term | Scope | Description | Example |
|
||||
|------|-------|-------------|---------|
|
||||
| **file_uuid** | Video file | Video file identifier (renamed from `video_uuid`) | `384b0ff44aaaa1f1` |
|
||||
| **identity_uuid** | Global identity | Global person identity (cross-file) | `a9a90105-6d6b-46ff-92da-0c3c1a57dff4` |
|
||||
| **face_id** | Single detection | Single face detection (frame-level) | `face_100` |
|
||||
| **trace_id** | Face tracking | Face tracking ID (Face Tracker output) | `2` |
|
||||
| **chunk_id** | Sentence chunk | Sentence chunk (from pre_chunks via rules) | `chunk_1` |
|
||||
| **speaker_id** | Speaker segment | Speaker ID (from ASRX) | `SPEAKER_0` |
|
||||
| **person_id** | ❌ **Deprecated** | Video-local person ID (removed in V4.0) | - |
|
||||
|
||||
### Architecture (V4.0)
|
||||
|
||||
```
|
||||
Face → Identity (Two-layer, direct binding)
|
||||
↓
|
||||
person_identities table: REMOVED
|
||||
file_identities table: ADDED (N:N relationship)
|
||||
```
|
||||
|
||||
### Key Changes (V3.x → V4.0)
|
||||
|
||||
| Change | V3.x | V4.0 |
|
||||
|--------|------|------|
|
||||
| **video_uuid** | Used everywhere | **file_uuid** |
|
||||
| **person_identities** | Required (303 records) | **Removed** |
|
||||
| **person_id APIs** | 28 endpoints | **Removed** (except register/bind) |
|
||||
| **Face binding** | Person → Identity | **Face → Identity** (direct) |
|
||||
| **Chunk binding** | Manual | **Auto** (time alignment) |
|
||||
|
||||
---
|
||||
|
||||
## Build & Run Commands
|
||||
|
||||
```bash
|
||||
# Build project (use debug builds for development/testing)
|
||||
# Build project
|
||||
cargo build
|
||||
cargo build --release
|
||||
cargo build --bin momentry
|
||||
cargo build --bin momentry_playground
|
||||
|
||||
@@ -203,29 +22,8 @@ cargo run -- server --host 0.0.0.0 --port 3002
|
||||
# Run playground (development binary)
|
||||
cargo run --bin momentry_playground -- server
|
||||
cargo run --bin momentry_playground -- --help
|
||||
|
||||
# Start servers (recommended — auto-build & logs to logs/)
|
||||
./run-server-3002.sh
|
||||
./run-server-3003.sh
|
||||
```
|
||||
|
||||
### Server Logs
|
||||
All runtime logs are centralized in `logs/`:
|
||||
```bash
|
||||
# View real-time logs
|
||||
tail -f logs/momentry_3002.log
|
||||
tail -f logs/momentry_3003.log
|
||||
|
||||
# Check recent errors
|
||||
grep -i "error\|panic\|FAIL" logs/momentry_*.log | tail -20
|
||||
```
|
||||
|
||||
### ⚠️ CRITICAL: `cargo build --release` PROHIBITION
|
||||
- **NEVER run `cargo build --release` unless the user explicitly says "release the binary" or "正式 release"**
|
||||
- `cargo build --release` is SLOW and only needed when producing a production binary for deployment
|
||||
- For all development, testing, debugging, and linting: use `cargo build` or `cargo check`
|
||||
- If uncertain, ALWAYS ask the user first
|
||||
|
||||
## Binaries
|
||||
|
||||
| Binary | Purpose | Port | Redis Prefix | Environment |
|
||||
@@ -384,15 +182,6 @@ src/
|
||||
### Server
|
||||
- `MOMENTRY_SERVER_PORT` - API server port (default: `3002` for production, `3003` for playground)
|
||||
- `MOMENTRY_REDIS_PREFIX` - Redis key prefix (default: `momentry:` for production, `momentry_dev:` for playground)
|
||||
- `MOMENTRY_API_KEY` - API key for Player online mode testing
|
||||
|
||||
### Testing API Key
|
||||
```bash
|
||||
export MOMENTRY_API_KEY="muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
|
||||
|
||||
# Test Player online mode
|
||||
cargo run --features player --bin momentry_player -- -o
|
||||
```
|
||||
|
||||
### Database
|
||||
- `DATABASE_URL` - PostgreSQL (default: `postgres://accusys@localhost:5432/momentry`)
|
||||
@@ -407,55 +196,11 @@ cargo run --features player --bin momentry_player -- -o
|
||||
- `MOMENTRY_PYTHON_PATH` - Python path (default: `/opt/homebrew/bin/python3.11`)
|
||||
- `MOMENTRY_SCRIPTS_DIR` - Scripts directory
|
||||
|
||||
### Critical Variables for Startup Scripts
|
||||
|
||||
**IMPORTANT**: Startup scripts must explicitly `export` these variables for Python subprocess inheritance.
|
||||
|
||||
#### Production (3002)
|
||||
Required exports in `run-server-3002.sh` and `run-worker-3002.sh`:
|
||||
```bash
|
||||
export MOMENTRY_OUTPUT_DIR=/Users/accusys/momentry/output
|
||||
export DATABASE_SCHEMA=public
|
||||
export MOMENTRY_REDIS_PREFIX=momentry:
|
||||
export MOMENTRY_SERVER_PORT=3002
|
||||
```
|
||||
|
||||
#### Playground (3003)
|
||||
Required exports in `run-server-3003.sh`:
|
||||
```bash
|
||||
export DATABASE_SCHEMA=dev
|
||||
export MOMENTRY_SERVER_PORT=3003
|
||||
export MOMENTRY_REDIS_PREFIX=momentry_dev:
|
||||
export MOMENTRY_OUTPUT_DIR=/Users/accusys/momentry/output_dev
|
||||
```
|
||||
|
||||
#### Why This Matters
|
||||
- Rust process loads `.env` via `dotenv`
|
||||
- Python subprocess inherits environment from Rust process
|
||||
- Without explicit `export`, dotenv variables are only available inside Rust
|
||||
- Python scripts like `store_traced_faces.py` will use hardcoded defaults if not exported
|
||||
|
||||
#### Config Directory
|
||||
Environment-specific configuration files:
|
||||
- `config/production.env` - Production-specific variables
|
||||
- `config/development.env` - Development-specific variables
|
||||
- `config/test.env` - Test environment (if needed)
|
||||
|
||||
### Processor Timeouts
|
||||
- `MOMENTRY_ASR_TIMEOUT` - ASR timeout in seconds (default: 3600)
|
||||
- `MOMENTRY_CUT_TIMEOUT` - CUT timeout in seconds (default: 3600)
|
||||
- `MOMENTRY_DEFAULT_TIMEOUT` - Default timeout (default: 7200)
|
||||
|
||||
### TMDb Integration (Face Clustering)
|
||||
- `TMDB_API_KEY` - TMDb API key for movie metadata lookup (required for `MOMENTRY_TMDB_PROBE_ENABLED=true`)
|
||||
- `MOMENTRY_TMDB_PROBE_ENABLED` - Enable TMDb probe during registration (default: `false`)
|
||||
- Register phase: searches TMDb by filename, creates identities with tmdb_id/tmdb_profile
|
||||
- Post-process phase: matches detected faces against TMDb identities via cosine similarity
|
||||
|
||||
### Synonym Expansion
|
||||
- `MOMENTRY_SYNONYM_FILES` - Comma-separated paths to synonym JSON files (e.g., `data/english_synonyms.json,data/llm_synonyms.json`)
|
||||
- `MOMENTRY_SYNONYM_FILE` - Single synonym JSON file path (deprecated, use above)
|
||||
|
||||
### Logging
|
||||
- `RUST_LOG` or `MOMENTRY_LOG_LEVEL` - Log level (default: `info`)
|
||||
|
||||
@@ -467,24 +212,6 @@ Environment-specific configuration files:
|
||||
- Monitor directory is a separate system (not Rust)
|
||||
- PythonExecutor provides unified script execution with timeout support
|
||||
- Redis 1.0.x for improved performance
|
||||
- FaceNet CoreML model (`models/facenet512.mlpackage`) replaces InsightFace for embedding extraction (MIT license, ANE-accelerated)
|
||||
|
||||
### LLM Synonym Generation
|
||||
|
||||
Generate synonym database using llama.cpp (Gemma4):
|
||||
|
||||
```bash
|
||||
# Generate full database (162 entries, ~5 minutes)
|
||||
python3 scripts/generate_synonyms_llamacpp.py
|
||||
|
||||
# Quick test
|
||||
python3 scripts/generate_synonyms_llamacpp.py --test
|
||||
|
||||
# Resume from existing file
|
||||
python3 scripts/generate_synonyms_llamacpp.py --resume
|
||||
|
||||
# Output: data/llm_synonyms.json (27 Chinese + 135 English words)
|
||||
```
|
||||
|
||||
## Task Management
|
||||
|
||||
@@ -586,95 +313,6 @@ shellcheck scripts/*.sh monitor/**/*.sh
|
||||
|
||||
**注意**: Hook 只檢查 error 等級的 shellcheck 問題，style 警告會顯示但不阻擋提交。
|
||||
|
||||
## Gitea Sync
|
||||
|
||||
主要 sync 管道為 Gitea：`http://192.168.110.200:3000/admin/momentry_core.git`
|
||||
|
||||
### 產生 Access Token（首次設定）
|
||||
|
||||
```bash
|
||||
# admin 帳號密碼為 AccusysTest!
|
||||
TOKEN=$(curl -s -X POST "http://192.168.110.200:3000/api/v1/users/admin/tokens" \
|
||||
-u "admin:AccusysTest!" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"m5max128_push","scopes":["write:repository"]}' | jq -r '.sha1')
|
||||
echo $TOKEN
|
||||
```
|
||||
|
||||
### 設定 Remote
|
||||
|
||||
```bash
|
||||
# 用 token 取代密碼
|
||||
git remote add origin http://admin:TOKEN@192.168.110.200:3000/admin/momentry_core.git
|
||||
|
||||
# 同步
|
||||
git pull origin main
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### Token 記錄
|
||||
|
||||
| 機器 | Token |
|
||||
|------|-------|
|
||||
| M5Max128 | `c33768c4cc26c0f4c575dcce832e92e5cf192773` (write:repository + write:user) |
|
||||
|
||||
**注意**: Token 有 write:repository scope，勿外洩。如需新增 token 給其他機器，各自產自己的 token。
|
||||
|
||||
## Release Workflow
|
||||
|
||||
### Release 前準備
|
||||
每次 release production binary 前，必須：
|
||||
|
||||
1. **建立 Release Tag**
|
||||
```bash
|
||||
git tag -a v0.X.X -m "Release vX.X.X - YYYY-MM-DD"
|
||||
git push origin v0.X.X
|
||||
```
|
||||
|
||||
2. **備份獨立 Source Code**
|
||||
```bash
|
||||
# 建立 release 獨立目錄
|
||||
RELEASE_DIR="/Users/accusys/momentry_core_releases/v0.X.X"
|
||||
mkdir -p "$RELEASE_DIR"
|
||||
|
||||
# 複製完整原始碼（排除不必要的檔案）
|
||||
rsync -av --exclude='.git' --exclude='target' --exclude='node_modules' \
|
||||
/Users/accusys/momentry_core_0.1/ "$RELEASE_DIR/"
|
||||
|
||||
# 記錄 release 資訊
|
||||
echo "Release: v0.X.X" > "$RELEASE_DIR/RELEASE_INFO.txt"
|
||||
echo "Date: $(date)" >> "$RELEASE_DIR/RELEASE_INFO.txt"
|
||||
echo "Git Commit: $(git rev-parse HEAD)" >> "$RELEASE_DIR/RELEASE_INFO.txt"
|
||||
echo "Binary: $(ls -la target/release/momentry)" >> "$RELEASE_DIR/RELEASE_INFO.txt"
|
||||
```
|
||||
|
||||
3. **備份 Binary**
|
||||
```bash
|
||||
cp target/release/momentry "$RELEASE_DIR/momentry_v0.X.X"
|
||||
cp target/release/momentry_playground "$RELEASE_DIR/momentry_playground_v0.X.X" 2>/dev/null
|
||||
```
|
||||
|
||||
4. **記錄資料庫 Schema**
|
||||
```bash
|
||||
pg_dump -U accusys -d momentry --schema-only > "$RELEASE_DIR/schema_v0.X.X.sql"
|
||||
```
|
||||
|
||||
5. **驗證環境變數配置**
|
||||
- ✅ Startup scripts export all required environment variables
|
||||
- ✅ Python scripts don't use hardcoded paths
|
||||
- ✅ Environment variables consistent across:
|
||||
- `.env` / `.env.development`
|
||||
- Startup script `export`
|
||||
- Python script `os.environ.get()`
|
||||
- ✅ Config directory has environment-specific files
|
||||
- ✅ AGENTS.md documents all required exports
|
||||
|
||||
### 重要性
|
||||
- 避免 release binary 與 current source code 不一致
|
||||
- 方便追蹤特定 release 的程式碼狀態
|
||||
- 必要時可快速復原或比對差異
|
||||
- 確保資料庫 schema 與程式碼版本對應
|
||||
|
||||
## Reference Documents
|
||||
|
||||
| 文件 | 用途 |
|
||||
@@ -773,132 +411,3 @@ Phase 1: marcom 建構 (現在) → Elementor 頁面建構
|
||||
Phase 2: 交付審視 (TBD) → 功能確認 / 重構評估
|
||||
Phase 3: OpenCode 重構 → 純程式碼實作，交付無 Elementor 依賴版本
|
||||
```
|
||||
|
||||
## M4 通知規範
|
||||
|
||||
### 固定通知方式
|
||||
|
||||
通知 M4 的唯一管道：**`M4_workspace/` 下建立回覆文件 + `git commit`**。不需口頭、即時訊息、郵件。
|
||||
|
||||
### 命名規則
|
||||
|
||||
```
|
||||
docs_v1.0/M4_workspace/YYYY-MM-DD_<topic>_response.md (回覆 M4 問題)
|
||||
docs_v1.0/M4_workspace/YYYY-MM-DD_<topic>.md (主動通報)
|
||||
docs_v1.0/M4_workspace/YYYY-MM-DD_<topic>_test_report.md (測試報告)
|
||||
```
|
||||
|
||||
### 觸發時機
|
||||
|
||||
| 情境 | 動作 |
|
||||
|------|------|
|
||||
| M4 提交問題報告到 `M4_workspace/` | 修復後，回覆 `*_response.md` |
|
||||
| 完成 M4 要求的任務 | 回覆 `*_response.md` |
|
||||
| 重大變更（模型替換、架構變更） | 主動通知 `*.md` |
|
||||
| 新測試包產出 | `*_test_report.md` |
|
||||
|
||||
### 交付檢查
|
||||
|
||||
1. 文件寫入 `docs_v1.0/M4_workspace/`
|
||||
2. `git add` 包含該文件
|
||||
3. `git commit` 含相關變更
|
||||
4. M4 透過 git log 查看
|
||||
|
||||
詳細規範見 `docs_v1.0/M4_workspace/M4_NOTIFICATION_PROTOCOL.md`。
|
||||
|
||||
## UUID Naming Rule
|
||||
|
||||
**Never use bare `uuid` in API route paths, query params, JSON keys, or code variable names. Always qualify:**
|
||||
|
||||
| Context | Must use | Never |
|
||||
|---------|----------|-------|
|
||||
| Video/file resource | `file_uuid` | `uuid` |
|
||||
| Identity resource | `identity_uuid` | `uuid` |
|
||||
| Query parameter | `file_uuid=`, `identity_uuid=` | `uuid=` |
|
||||
| Route path | `:file_uuid`, `:identity_uuid` | `:uuid` |
|
||||
| JSON key | `"file_uuid"`, `"identity_uuid"` | `"uuid"` |
|
||||
|
||||
This applies to docs, code, API responses, and curl examples. Exceptions: internal database primary key names (e.g. `identities.uuid` column).
|
||||
|
||||
## Document Compliance Checklist
|
||||
|
||||
Before creating any file in `docs_v1.0/` (API_WORKSPACE, GUIDES, REFERENCE, DESIGN, OPERATIONS, INTEGRATIONS), verify all items below.
|
||||
**IMPORTANT**: API functional documents are generated from `API_WORKSPACE/modules/`. Edit modules there, then run `make deploy` in `API_WORKSPACE/` to update `GUIDES/`. Never edit generated files in `GUIDES/` directly. See `DESIGN/Modular_Doc_System_V1.0.md` for the full system design.
|
||||
|
||||
### P0 — Mandatory (7 items)
|
||||
|
||||
| # | Check | Rule |
|
||||
|---|-------|------|
|
||||
| 1 | YAML frontmatter | `title`, `version`, `date`, `author`, `status` present |
|
||||
| 2 | Version history | Table at bottom of file tracking changes |
|
||||
| 3 | Top info table | scope, status, applicable to, etc. |
|
||||
| 4 | PascalCase filename | e.g. `DetectorRegistry.md`, not `detector_registry.md` |
|
||||
| 5 | `_` separator | Within filenames use `_`, never spaces or other chars |
|
||||
| 6 | English content | Entire file in English |
|
||||
| 7 | Correct directory | File must reside in appropriate directory: `API_WORKSPACE/modules/` (API endpoint modules), `GUIDES/` (user docs, generated), `REFERENCE/` (data models), `DESIGN/` (architecture), `OPERATIONS/` (infra/release), `INTEGRATIONS/` (n8n/tests) |
|
||||
|
||||
### P0b — UUID Naming
|
||||
|
||||
| # | Check | Rule |
|
||||
|---|-------|------|
|
||||
| 8 | `file_uuid` not bare `uuid` | All file references use `file_uuid` (see UUID Naming Rule above) |
|
||||
| 9 | `identity_uuid` not bare `uuid` | All identity references use `identity_uuid` |
|
||||
|
||||
### P1 — Suggested (3 items)
|
||||
|
||||
| # | Check | Note |
|
||||
|---|-------|------|
|
||||
| 1 | Cross-references | Link to related docs in API_WORKSPACE/, GUIDES/, REFERENCE/, DESIGN/, OPERATIONS/ |
|
||||
| 2 | Glossary terms | Define non-obvious terms inline or link glossary |
|
||||
| 3 | Diagrams | Include Mermaid/ASCII diagram for complex topics |
|
||||
|
||||
### Exception
|
||||
|
||||
`M4_workspace/` files are exempt from this checklist (free-format reply documents).
|
||||
|
||||
---
|
||||
|
||||
## Delivery Procedure
|
||||
|
||||
完整交付程序（M4_workspace → M5 → Release → Deploy → Public）見：
|
||||
|
||||
`docs_v1.0/OPERATIONS/DELIVERY_PROCEDURE.md`
|
||||
|
||||
## Session Summary (2026-07-01: Search Mode Fixes)
|
||||
|
||||
### Goal
|
||||
Fix search modes: Keyword BM25 ranking + People search migration to Qdrant + Qdrant scroll pagination
|
||||
|
||||
### Done
|
||||
- **Keyword/BM25 search (`search_bm25`)**: Replaced hardcoded 1.0 score with PostgreSQL FTS (`ts_rank` + `plainto_tsquery`). Now ranks results by relevance instead of flat 1.0.
|
||||
- **Smart search merge**: Passes real FTS score through instead of fixed 0.5, so keyword-only results are properly differentiated.
|
||||
- **Qdrant scroll_points**: Added `offset` parameter for pagination support; new `scroll_all_points()` method handles multi-page scroll automatically.
|
||||
- **get_identity_traces**: Fixed broken pagination loop (always fetched same first 1000 points) by switching to `scroll_all_points`.
|
||||
- **People search (`search_persons_internal`)**: Replaced `face_detections` JOIN in universal search with Qdrant `_faces` scroll + Rust aggregation (count per identity per file, frame→second via FPS).
|
||||
- **People search (`search_persons_by_query`)**: Same migration for the REST API person search endpoint.
|
||||
- **Payload field fix**: `_faces` uses `frame` (integer) not `timestamp_secs` (float). Fixed both `search_persons_internal` and `search_persons_by_query` to read `frame` and convert via `frame / fps`.
|
||||
|
||||
### Key Files Changed
|
||||
- `src/core/db/qdrant_db.rs`: `scroll_points` → offset pagination, new `scroll_all_points`
|
||||
- `src/api/identity_binding.rs`: Use `scroll_all_points` instead of broken loop
|
||||
- `src/api/universal_search.rs`: Rewrote `search_persons_internal` and `search_persons_by_query` to use Qdrant
|
||||
- `src/core/db/postgres_db.rs`: `search_bm25` → PostgreSQL FTS ranking
|
||||
- `src/api/search.rs`: Pass real FTS scores in merge, removed unused `KEYWORD_FIXED_SCORE`
|
||||
|
||||
### Done This Session
|
||||
- **Qdrant scroll pagination**: `scroll_points` now accepts `offset` param + returns `next_page_offset`; new `scroll_all_points()` handles multi-page scroll automatically
|
||||
- **get_identity_traces pagination fix**: No longer fetches same 1000 points in infinite loop
|
||||
- **Keyword BM25**: `search_bm25` replaced hardcoded 1.0 score with PostgreSQL `ts_rank` + `plainto_tsquery`; `smart_search` passes real FTS scores instead of fixed 0.5
|
||||
- **People search → Qdrant**: Both `search_persons_internal` and `search_persons_by_query` replaced `face_detections` JOIN with Qdrant `_faces` scroll + Rust aggregation (count/group/sort). Fixed `timestamp_secs` → `frame` + `frame/fps` conversion
|
||||
- **list_face_candidates → Qdrant**: `identities.rs` unbound faces query now scrolls `_faces` with `is_null: identity_id` filter, sorts by confidence DESC in Rust
|
||||
- **list_unassigned_traces → Qdrant**: `identities.rs` unbound traces query now scrolls `_faces` with `is_null: identity_id` + `trace_id > 0` filter, groups by (file_uuid, trace_id) in Rust, picks best face per trace
|
||||
- **get_identity_chunks → identity_bindings**: Replaced `face_detections` frame-range JOIN with `identity_bindings` + `chunk.metadata->>'trace_id'`
|
||||
- **postgres_db.rs 5 remaining READs → Qdrant**: `get_trace_count_by_file`, `get_trace_frame_count_distribution`, `get_identity_files`, `get_identity_faces`, `get_file_faces` all migrated to `_faces` scroll + Rust aggregation
|
||||
- **agent/tools.rs fully migrated**: `exec_find_file`, `exec_list_files`, `exec_tkg_query` (8 sub-queries), `exec_identity_text`, `exec_identities_search` — all face_detections JOINs replaced with Qdrant scroll or identity_bindings
|
||||
- **job_worker.rs + storage.rs**: Remaining face_detections READs migrated to Qdrant scroll
|
||||
|
||||
### Remaining face_detections references (all inactive/safe)
|
||||
- Schema definition (CREATE TABLE/INDEX in `postgres_db.rs`)
|
||||
- `store_face_detections_batch` — already skipped (Phase 1)
|
||||
- `workspace_sqlite.rs` — local processing DB, separate from PG
|
||||
- `bin/release.rs` — standalone release utility
|
||||
|
||||
Generated
+273
-1059
File diff suppressed because it is too large
Load Diff
+11
-68
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "momentry_core"
|
||||
version = "1.0.0"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
authors = ["Momentry Team"]
|
||||
description = "Digital asset management system with video analysis and RAG"
|
||||
@@ -11,9 +11,8 @@ anyhow = "1.0"
|
||||
thiserror = "1.0"
|
||||
tokio = { version = "1", features = ["full"] }
|
||||
tracing = "0.1"
|
||||
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
|
||||
tracing-subscriber = "0.3"
|
||||
once_cell = "1.19"
|
||||
libc = "0.2"
|
||||
dotenv = "0.15"
|
||||
|
||||
# CLI
|
||||
@@ -26,42 +25,32 @@ futures-util = "0.3"
|
||||
# Serialization
|
||||
serde = { version = "1.0", features = ["derive"] }
|
||||
serde_json = "1.0"
|
||||
regex = "1"
|
||||
chrono = { version = "0.4", features = ["serde"] }
|
||||
|
||||
# UUID
|
||||
sha2 = "0.10"
|
||||
hex = "0.4"
|
||||
uuid = { version = "1.0", features = ["v4"] }
|
||||
mac_address = "1.1"
|
||||
|
||||
# Security
|
||||
subtle = "2.5"
|
||||
aes-gcm = "0.10"
|
||||
base64 = "0.22"
|
||||
argon2 = "0.5"
|
||||
jsonwebtoken = "9.3"
|
||||
|
||||
# Text processing
|
||||
jieba-rs = "0.8.1"
|
||||
ferrous-opencc = { version = "0.3.1", features = ["s2t-conversion", "t2s-conversion"] }
|
||||
# Security
|
||||
subtle = "2.5"
|
||||
aes-gcm = "0.10"
|
||||
base64 = "0.22"
|
||||
|
||||
# Cache
|
||||
moka = { version = "0.12", features = ["future"] }
|
||||
|
||||
# Database
|
||||
redis = { version = "1.0", features = ["tokio-comp", "connection-manager"] }
|
||||
sqlx = { version = "0.8", features = ["runtime-tokio", "postgres", "sqlite", "json", "chrono", "uuid"] }
|
||||
sqlx = { version = "0.8", features = ["runtime-tokio", "postgres", "sqlite", "json", "chrono"] }
|
||||
mongodb = { version = "2", features = ["tokio-runtime"] }
|
||||
bson = { version = "2", features = ["chrono-0_4"] }
|
||||
qdrant-client = "1.7"
|
||||
reqwest = { version = "0.12", features = ["json", "gzip", "zstd"] }
|
||||
pgvector = { version = "0.3", features = ["sqlx"] }
|
||||
reqwest = { version = "0.12", features = ["json"] }
|
||||
|
||||
# HTTP Server
|
||||
axum = { version = "0.7", features = ["multipart"] }
|
||||
axum = "0.7"
|
||||
tower = "0.4"
|
||||
tower-http = { version = "0.5", features = ["cors", "fs"] }
|
||||
|
||||
# API Documentation
|
||||
utoipa = { version = "4", features = ["axum_extras", "chrono", "uuid"] }
|
||||
@@ -82,9 +71,9 @@ crossterm = "0.28"
|
||||
|
||||
# Terminal
|
||||
atty = "0.2"
|
||||
tokio-util = { version = "0.7.18", features = ["io"] }
|
||||
|
||||
# System
|
||||
libc = "0.2"
|
||||
|
||||
[lib]
|
||||
name = "momentry_core"
|
||||
@@ -92,20 +81,12 @@ path = "src/lib.rs"
|
||||
|
||||
[features]
|
||||
default = []
|
||||
player = ["sdl2"]
|
||||
|
||||
[dependencies.sdl2]
|
||||
version = "0.35"
|
||||
optional = true
|
||||
player = []
|
||||
|
||||
[[bin]]
|
||||
name = "momentry"
|
||||
path = "src/main.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "momentry-cli"
|
||||
path = "src/bin/cli.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "momentry_player"
|
||||
path = "src/player/main.rs"
|
||||
@@ -113,41 +94,3 @@ path = "src/player/main.rs"
|
||||
[[bin]]
|
||||
name = "momentry_playground"
|
||||
path = "src/playground.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "fix_chunks"
|
||||
path = "src/bin/fix_chunks.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "migrate_chinese_text"
|
||||
path = "src/bin/migrate_chinese_text.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "test_bm25_simple"
|
||||
path = "src/bin/test_bm25_simple.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "integrated_player"
|
||||
path = "src/bin/integrated_player.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "release"
|
||||
path = "src/bin/release.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "vectorize_missing"
|
||||
path = "src/bin/vectorize_missing.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "sync_qdrant_from_pg"
|
||||
path = "src/bin/sync_qdrant_from_pg.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "service"
|
||||
path = "src/bin/service.rs"
|
||||
|
||||
[build-dependencies]
|
||||
chrono = "0.4"
|
||||
|
||||
[dev-dependencies]
|
||||
tempfile = "3"
|
||||
|
||||
@@ -1,277 +0,0 @@
|
||||
# Identity Best-Face API
|
||||
|
||||
**狀態：** 規劃中
|
||||
**提出日期：** 2026-06-01
|
||||
**提出者：** WordPress Portal 前端團隊
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景
|
||||
|
||||
WordPress Portal 的 People 頁面需要在 identity detail view 與 grid card 中顯示代表臉部縮圖。目前前端作法：
|
||||
|
||||
1. `GET /identity/{uuid}/traces` → 取得所有 trace 列表（含 `avg_confidence`）
|
||||
2. 對每個 trace 載入第一幀 thumbnail → `GET /file/{uuid}/trace/{tid}/thumbnail`
|
||||
3. 從有 thumbnail 的 trace 中，選 `avg_confidence` 最高者作為代表圖
|
||||
|
||||
### 現有問題
|
||||
|
||||
- **品質不佳**：trace thumbnail 固定取第一幀，不一定是該 trace 內最清晰或正面的臉部畫面
|
||||
- **浪費頻寬**：前端需發送大量並行請求（最多 20 trace × thumbnail），多數 thumbnail 最終不會被使用
|
||||
- **無快取**：每次進入 detail view 都要重複載入所有 thumbnail
|
||||
- **不一致**：同樣 identity 在 grid card 與 detail view 可能顯示不同代表圖
|
||||
|
||||
---
|
||||
|
||||
## 2. 目標
|
||||
|
||||
後端新增一個 endpoint，對指定 identity **跨所有 trace** 選出品質最佳（最清晰）的臉部畫面，並提供可直接使用的縮圖 URL，支援 disk cache。
|
||||
|
||||
---
|
||||
|
||||
## 3. API 規格
|
||||
|
||||
### `GET /api/v1/identity/:identity_uuid/best-face`
|
||||
|
||||
無 query parameter。
|
||||
|
||||
#### 成功回應 `200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "a6fb22eebefaef17e62af874997c5944",
|
||||
"name": "Audrey Hepburn",
|
||||
"source": "fresh",
|
||||
"best": {
|
||||
"file_uuid": "a6fb22eebefaef17e62af874997c5944",
|
||||
"trace_id": 42,
|
||||
"frame_number": 3120,
|
||||
"timestamp_secs": 124.8,
|
||||
"bbox": {
|
||||
"x": 240,
|
||||
"y": 180,
|
||||
"width": 120,
|
||||
"height": 160
|
||||
},
|
||||
"confidence": 0.97,
|
||||
"quality_score": 18624.0,
|
||||
"blur_score": 2.1,
|
||||
"thumbnail_url": "/api/v1/file/a6fb22eebefaef17e62af874997c5944/trace/42/thumbnail"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 無可用臉部 `200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "a6fb22eebefaef17e62af874997c5944",
|
||||
"name": "Audrey Hepburn",
|
||||
"source": "fresh",
|
||||
"best": null
|
||||
}
|
||||
```
|
||||
|
||||
#### 欄位說明
|
||||
|
||||
| 欄位 | 型態 | 說明 |
|
||||
|------|------|------|
|
||||
| `success` | boolean | 請求是否成功 |
|
||||
| `identity_uuid` | string | identity UUID（32字元無連字號） |
|
||||
| `name` | string | identity 名稱 |
|
||||
| `source` | string | `"fresh"`（即時計算）或 `"cache"`（來自 disk cache） |
|
||||
| `best` | object/null | 最佳臉部資訊，無可用臉部時為 `null` |
|
||||
| `best.file_uuid` | string | 該臉部所屬檔案 UUID |
|
||||
| `best.trace_id` | int | 該臉部所屬 trace ID |
|
||||
| `best.frame_number` | int | 代表臉的影格編號 |
|
||||
| `best.timestamp_secs` | float | 代表臉的時間戳（秒） |
|
||||
| `best.bbox` | object | 臉部 bounding box `{x, y, width, height}` |
|
||||
| `best.confidence` | float | 該臉部的 detection confidence |
|
||||
| `best.quality_score` | float | 品質分數 = `(width * height) * confidence` |
|
||||
| `best.blur_score` | float | 模糊度分數（ffmpeg blurdetect），越低越清晰 |
|
||||
| `best.thumbnail_url` | string | 縮圖 URL（相對路徑，可直接用於瀏覽器） |
|
||||
|
||||
---
|
||||
|
||||
## 4. 實作建議
|
||||
|
||||
### 4.1 建議放置位置
|
||||
|
||||
**選項 A（建議）：** `src/api/trace_agent_api.rs`
|
||||
|
||||
- 原因：核心邏輯重用 `select_rep_face()`（目前為 `pub(crate)`，位於同一檔案），無需修改既有的 function visibility
|
||||
- 在 `trace_agent_routes()` 中新增路由
|
||||
|
||||
**選項 B：** `src/api/identity_binding.rs`
|
||||
|
||||
- 需將 `select_rep_face` 改為 `pub` 才能跨檔案呼叫
|
||||
- 路由語意上更接近 identity 操作
|
||||
|
||||
### 4.2 演算法
|
||||
|
||||
```
|
||||
1. DISK CACHE CHECK
|
||||
路徑：{OUTPUT_DIR}/identities/{uuid}/best_face.json
|
||||
讀取 identity.json 的 updated_at，與 cache 中記錄的版本比較
|
||||
若 cache 未過期 → 直接回傳（source: "cache"）
|
||||
若無 cache 或已過期 → 繼續計算
|
||||
|
||||
2. QUERY IDENTITY
|
||||
SELECT id, name FROM identities
|
||||
WHERE REPLACE(uuid::text, '-', '') = $1
|
||||
|
||||
3. QUERY TOP N TRACES
|
||||
SELECT fd.file_uuid, fd.trace_id,
|
||||
AVG(fd.confidence)::float8 AS avg_conf
|
||||
FROM {schema}.face_detections fd
|
||||
WHERE fd.identity_id = $1
|
||||
AND fd.confidence > 0.7
|
||||
AND (fd.metadata->>'qc_ok' IS NULL
|
||||
OR (fd.metadata->>'qc_ok')::boolean = true)
|
||||
GROUP BY fd.file_uuid, fd.trace_id
|
||||
ORDER BY avg_conf DESC
|
||||
LIMIT 5
|
||||
|
||||
4. FOR EACH TRACE (並行)
|
||||
select_rep_face(pool, file_uuid, trace_id, err_fn)
|
||||
→ 回傳該 trace 內 blur_score 最低（最清晰）的臉
|
||||
失敗則 skip（log warning）
|
||||
|
||||
5. SELECT BEST AMONG RESULTS
|
||||
主排序：blur_score ASC（越低越清晰）
|
||||
次排序：quality_score DESC（blur_score 差距 < 0.5 時）
|
||||
全部失敗 → best = null
|
||||
|
||||
6. WRITE DISK CACHE
|
||||
路徑：{OUTPUT_DIR}/identities/{uuid}/best_face.json
|
||||
內容：best 欄位 + 計算時間 + identity updated_at
|
||||
|
||||
7. RESPONSE
|
||||
```
|
||||
|
||||
### 4.3 效能參數
|
||||
|
||||
| 參數 | 值 | 說明 |
|
||||
|------|----|------|
|
||||
| TOP N | 5 | 只對 confidence 最高的 5 個 trace 做 blurdetect |
|
||||
| confidence 門檻 | > 0.7 | 同既有的 `select_rep_face` 邏輯 |
|
||||
| QC 過濾 | qc_ok = true/null | 同既有邏輯 |
|
||||
| ffmpeg timeout | inherit from Command | 每個 trace 約 1-3s |
|
||||
| cache TTL | 直到下一次 bind/unbind/merge | 事件驅動失效 |
|
||||
|
||||
### 4.4 快取策略
|
||||
|
||||
**寫入時機：** `get_identity_best_face` 計算完成後
|
||||
|
||||
**失效時機（刪除 `best_face.json`）：**
|
||||
|
||||
| 觸發 operation | 所在檔案 | 備註 |
|
||||
|---------------|---------|------|
|
||||
| `bind_trace` (POST) | `identity_binding.rs` | 新增 face 關聯 |
|
||||
| `unbind` (POST) | `identity_binding.rs` | 移除 face 關聯 |
|
||||
| `mergeinto` (POST) | `identity_binding.rs` | source + target 雙雙清除 |
|
||||
| `profile-image` (POST) | `identity_api.rs` | 使用者上傳新大頭照 |
|
||||
|
||||
**Cache 驗證機制：** 儲存計算時的 `identity.updated_at`，每次請求時比對：
|
||||
- 若 identity 的 `updated_at` 未變 → cache 有效
|
||||
- 若已變 → 重新計算
|
||||
|
||||
### 4.5 建議的新增/修改檔案
|
||||
|
||||
| 檔案 | 動作 | 說明 |
|
||||
|------|------|------|
|
||||
| `src/api/trace_agent_api.rs` | **新增** handler + struct + route | ~+130 行 |
|
||||
| `src/api/identity_binding.rs` | **修改** 3 處 + cache invalidation helper | ~+25 行 |
|
||||
| `src/api/identity_api.rs` | **修改** 1 處（profile-image POST） | ~+5 行 |
|
||||
|
||||
### 4.6 需要的新 struct
|
||||
|
||||
**`src/api/trace_agent_api.rs`**（或獨立檔案 `src/core/identity_best_face.rs`）：
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
pub struct BestFaceResponse {
|
||||
pub success: bool,
|
||||
pub identity_uuid: String,
|
||||
pub name: String,
|
||||
pub source: String,
|
||||
pub best: Option<BestFaceResult>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
pub struct BestFaceResult {
|
||||
pub file_uuid: String,
|
||||
pub trace_id: i32,
|
||||
pub frame_number: i64,
|
||||
pub timestamp_secs: f64,
|
||||
pub bbox: RepFaceBbox,
|
||||
pub confidence: f64,
|
||||
pub quality_score: f64,
|
||||
pub blur_score: f64,
|
||||
pub thumbnail_url: String,
|
||||
}
|
||||
```
|
||||
|
||||
### 4.7 Cache Invalidation Helper Function
|
||||
|
||||
```rust
|
||||
async fn invalidate_best_face_cache(output_dir: &str, uuid_clean: &str) {
|
||||
let path = format!("{}/identities/{}/best_face.json", output_dir, uuid_clean);
|
||||
let _ = tokio::fs::remove_file(path).await;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 前端整合參考（供後端團隊理解使用情境）
|
||||
|
||||
WP snippet 72 (`ms-people.js`) 的 `loadPersonDetail` 中，優先使用新 endpoint：
|
||||
|
||||
```js
|
||||
async function loadPersonDetail(person) {
|
||||
if (person.thumb && person._hasProfileImage) return;
|
||||
|
||||
try {
|
||||
const res = await apiFetch('/identity/' + person.id + '/best-face');
|
||||
if (res?.success && res?.best) {
|
||||
const b = res.best;
|
||||
person.thumb = `${API_BASE}/file/${b.file_uuid}/trace/${b.trace_id}/thumbnail?api_key=${API_KEY}`;
|
||||
person._hasProfileImage = true;
|
||||
updateDetailAvatar(person);
|
||||
return;
|
||||
}
|
||||
} catch (e) { /* fallback to legacy */ }
|
||||
|
||||
// 原邏輯：traces → thumbnails → confidence sort
|
||||
}
|
||||
```
|
||||
|
||||
同樣可用於 grid card 的代表圖載入（`loadGridThumbnails`）：
|
||||
|
||||
```js
|
||||
// 一次性載入所有 pending identity 的 best-face
|
||||
const results = await Promise.allSettled(
|
||||
persons.map(p => apiFetch('/identity/' + p.id + '/best-face'))
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 驗收標準
|
||||
|
||||
1. `GET /api/v1/identity/{uuid}/best-face` → `200` + valid JSON
|
||||
2. 有 trace 的 identity → `best` 不為 null，且 `blur_score` 為該 identity 所有 trace 中最低
|
||||
3. 無 trace 的 identity → `best: null`
|
||||
4. 短時間內重複請求同一 identity → `source: "cache"`，回應時間 < 10ms
|
||||
5. 綁定新 trace 後再次請求 → `source: "fresh"`（cache 已正確失效）
|
||||
6. `thumbnail_url` 可直接用於 `<img>` 顯示
|
||||
|
||||
---
|
||||
|
||||
## 7. 風險與注意事項
|
||||
|
||||
- **首次請求延遲**：對有大量 trace 的 identity（如主角），首次請求可能需 5-15 秒。建議前端顯示 loading state
|
||||
- **ffmpeg 資源**：同時多個請求可能導致高 CPU 使用。可考慮加入 per-identity lock 避免重複計算
|
||||
- **邊界案例**：trace 內的 faces 全部 confidence ≤ 0.7 或 qc_ok=false，則該 trace 被跳過，可能導致 `best: null`
|
||||
@@ -1,3 +0,0 @@
|
||||
# momentry_core
|
||||
|
||||
Digital asset management system with video analysis and RAG - Production version with API Key authentication
|
||||
@@ -1,78 +0,0 @@
|
||||
# Sync Notes 2026-05-21
|
||||
|
||||
## M5Max128 收到後需要做的事
|
||||
|
||||
```bash
|
||||
cd ~/momentry_core
|
||||
git pull origin main # 拉取所有變更
|
||||
cat SYNC_V1.1.md # 閱讀此文件
|
||||
|
||||
# 資料庫變更（必須先執行，否則 worker 會 fail）
|
||||
psql -U accusys -d momentry -c "ALTER TABLE public.pre_chunks ALTER COLUMN coordinate_index SET DEFAULT 0;"
|
||||
|
||||
# 重建 + 重啟
|
||||
cargo build --release --bin momentry
|
||||
./run-server-3002.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bugs Fixed (13)
|
||||
|
||||
| # | 問題 | 根因 | 修復 |
|
||||
|---|------|------|------|
|
||||
| 1 | `GET /identity/:uuid/files` 空資料 | SQL 缺 `REPLACE(uuid)` + 缺 `JOIN videos` | 改用 `REPLACE(uuid::text...)` + JOIN videos + `frame_number/fps` |
|
||||
| 2 | `GET /identity/:uuid/faces` crash + 空 | `i64`/`INT4` 型別不符 + 硬編碼 NULL/0 | `id::bigint`、`confidence::float8` + 真實欄位 |
|
||||
| 3 | `GET /identity/:uuid` crash | `IdentityDetailRecord.id` 是 `i64` 但 DB 是 `INT4` | `id::bigint as id` |
|
||||
| 4 | `GET /file/:uuid/identities` 空 | 雙重 stub（handler + DB 都 `Vec::new()`） | 完整實作 + 正確 total count |
|
||||
| 5 | `GET /identities/search?q=Louis` 500 | `c.text_content` NULL 但 Rust tuple 用 `String` | 改 `Option<String>` |
|
||||
| 6 | `POST /search/universal` person type first/last_time null | `search_persons_internal` 用 `timestamp_secs` | 改 `frame_number/fps` + JOIN videos |
|
||||
| 7 | faces/files/chunks total 不正確 | `total: data.len()` | 獨立 COUNT 查詢 |
|
||||
| 8 | `GET /identity/:uuid/traces` 無分頁 | 缺 page/page_size | 新增 `TracesQuery` + LIMIT/OFFSET |
|
||||
| 9 | 身分比對 frame-level 不穩定 | frame-level Qdrant | 改 **trace-level**（AVG embedding per trace） |
|
||||
| 10 | Charade face embedding 不在 Qdrant | 沒跑 `sync_face_embeddings` | match API 自動 push + ANN search |
|
||||
| 11 | 無眼睛 face 推入 Qdrant | 無 QC 過濾 | `face_landmark_qc.py --apply` + Qdrant sync 過濾 `qc_ok` |
|
||||
| 12 | TMDb 比對 dev/prod 不一致 | Qdrant ANN 不同 collection | trace-level 改善穩定性 |
|
||||
| 13 | `faces/files/chunks total` 顯示 page_size | `total: data.len()` | 改為獨立 COUNT 查詢 |
|
||||
|
||||
## ✨ 新功能 (6)
|
||||
|
||||
| # | 功能 | 說明 |
|
||||
|---|------|------|
|
||||
| 1 | `POST /api/v1/tmdb/fetch` | 從 TMDb 下載 cast → 建立 identity + json + jpg + Qdrant |
|
||||
| 2 | `POST /api/v1/agents/tmdb/match/:file_uuid` | 推 face → Qdrant ANN search → bind identity |
|
||||
| 3 | `GET /api/v1/identity/:uuid/status` | 檢查 identity.json + profile.jpg 是否存在 |
|
||||
| 4 | `/health` 新增 watcher/worker/時區 | `watcher_running`、`worker_running`、`system_timezone` |
|
||||
| 5 | `SYSTEM_TIMEZONE` config | 自動偵測系統時區，可 `MOMENTRY_TIMEZONE` 覆蓋 |
|
||||
| 6 | `GET /identity/:uuid/traces` 分頁 | `?page=1&page_size=20` |
|
||||
|
||||
## 🔧 資料庫變更
|
||||
|
||||
```sql
|
||||
-- 必須執行（否則 worker 的 CUT processor 會失敗）
|
||||
ALTER TABLE public.pre_chunks ALTER COLUMN coordinate_index SET DEFAULT 0;
|
||||
|
||||
-- 選擇性（face_landmark_qc.py --apply 需要）
|
||||
ALTER TABLE public.face_detections ADD COLUMN metadata jsonb DEFAULT '{}'::jsonb;
|
||||
```
|
||||
|
||||
## 🗑️ 清理
|
||||
|
||||
- 刪除 2,769 個孤兒 `person_xxx` identity（無 face_detections）
|
||||
- `person_identities` + `person_appearances` table 已 DROP
|
||||
|
||||
## 📂 主要檔案變更
|
||||
|
||||
| 檔案 | 說明 |
|
||||
|------|------|
|
||||
| `src/api/identity_api.rs` | identity detail/files/faces total 修正 + status endpoint |
|
||||
| `src/api/identity_binding.rs` | traces 分頁（新增 `page`/`page_size`/`total`） |
|
||||
| `src/api/server.rs` | health 新增 watcher/worker/system_timezone |
|
||||
| `src/api/tmdb_api.rs` | **新檔案** — tmdb/fetch + match 端點 |
|
||||
| `src/api/universal_search.rs` | person search 改 frame_number/fps |
|
||||
| `src/core/config.rs` | 新增 SYSTEM_TIMEZONE |
|
||||
| `src/core/db/qdrant_db.rs` | search_face_collection + sync_trace_embeddings + batch upsert |
|
||||
| `src/core/db/postgres_db.rs` | get_identity_files/faces 修正 + get_file_identities 實作 |
|
||||
| `src/core/tmdb/probe.rs` | extract_movie_name 改進（只取 `(` 前） |
|
||||
| `scripts/face_landmark_qc.py` | 新增 `--apply` + `--schema` 參數 |
|
||||
| `Cargo.toml` | reqwest 加 `gzip` feature |
|
||||
@@ -1,81 +0,0 @@
|
||||
use std::collections::BTreeMap;
|
||||
use std::path::Path;
|
||||
|
||||
fn main() {
|
||||
let version = std::env::var("CARGO_PKG_VERSION").unwrap_or_else(|_| "unknown".to_string());
|
||||
|
||||
let git_hash = std::process::Command::new("git")
|
||||
.args(["rev-parse", "--short", "HEAD"])
|
||||
.output()
|
||||
.ok()
|
||||
.and_then(|o| String::from_utf8(o.stdout).ok())
|
||||
.map(|s| s.trim().to_string())
|
||||
.unwrap_or_else(|| "unknown".to_string());
|
||||
|
||||
let timestamp = std::process::Command::new("date")
|
||||
.args(["-u", "+%Y-%m-%dT%H:%M:%SZ"])
|
||||
.output()
|
||||
.ok()
|
||||
.and_then(|o| String::from_utf8(o.stdout).ok())
|
||||
.map(|s| s.trim().to_string())
|
||||
.unwrap_or_else(|| "unknown".to_string());
|
||||
|
||||
println!("cargo:rustc-env=BUILD_VERSION={}", version);
|
||||
println!("cargo:rustc-env=BUILD_GIT_HASH={}", git_hash);
|
||||
println!("cargo:rustc-env=BUILD_TIMESTAMP={}", timestamp);
|
||||
|
||||
// ── Schema migration manifest ──
|
||||
// Scan release/migrate_*.sql, compute SHA256, embed as JSON string
|
||||
let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_else(|_| ".".to_string());
|
||||
let release_dir = Path::new(&manifest_dir).join("release");
|
||||
|
||||
let mut migrations = BTreeMap::new(); // sorted by filename
|
||||
if let Ok(entries) = std::fs::read_dir(&release_dir) {
|
||||
for entry in entries.flatten() {
|
||||
let path = entry.path();
|
||||
let fname = path.file_name().and_then(|n| n.to_str()).unwrap_or("");
|
||||
if fname.starts_with("migrate_") && fname.ends_with(".sql") {
|
||||
if let Ok(content) = std::fs::read(&path) {
|
||||
let hash = sha256_hex(&content);
|
||||
migrations.insert(fname.to_string(), hash);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Encode as comma-separated: name1:hash1,name2:hash2,...
|
||||
let manifest: String = migrations
|
||||
.iter()
|
||||
.map(|(name, hash)| format!("{}:{}", name, hash))
|
||||
.collect::<Vec<_>>()
|
||||
.join(",");
|
||||
println!("cargo:rustc-env=REQUIRED_MIGRATIONS={}", manifest);
|
||||
println!(
|
||||
"cargo:info=Embedded {} migration checksums",
|
||||
migrations.len()
|
||||
);
|
||||
}
|
||||
|
||||
fn sha256_hex(data: &[u8]) -> String {
|
||||
use std::io::Write;
|
||||
use std::process::{Command, Stdio};
|
||||
if let Ok(mut child) = Command::new("shasum")
|
||||
.arg("-a")
|
||||
.arg("256")
|
||||
.stdin(Stdio::piped())
|
||||
.stdout(Stdio::piped())
|
||||
.spawn()
|
||||
{
|
||||
if let Some(mut stdin) = child.stdin.take() {
|
||||
let _ = stdin.write_all(data);
|
||||
}
|
||||
if let Ok(out) = child.wait_with_output() {
|
||||
if let Ok(s) = String::from_utf8(out.stdout) {
|
||||
if let Some(hash) = s.split(' ').next() {
|
||||
return hash.to_string();
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
"unknown".to_string()
|
||||
}
|
||||
@@ -1,26 +0,0 @@
|
||||
use sqlx::postgres::PgPoolOptions;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let pool = PgPoolOptions::new()
|
||||
.max_connections(1)
|
||||
.connect("postgres://accusys@localhost:5432/momentry")
|
||||
.await?;
|
||||
|
||||
let row: Option<(i32, String, String, Option<String>)> = sqlx::query_as(
|
||||
"SELECT id, uuid, status, processors FROM monitor_jobs WHERE uuid = 'd8acb03870f0cc9b14e01f14a7bf24d6' ORDER BY id DESC LIMIT 1"
|
||||
)
|
||||
.fetch_optional(&pool)
|
||||
.await?;
|
||||
|
||||
if let Some((id, uuid, status, processors)) = row {
|
||||
println!("Job ID: {}", id);
|
||||
println!("UUID: {}", uuid);
|
||||
println!("Status: {}", status);
|
||||
println!("Processors: {:?}", processors);
|
||||
} else {
|
||||
println!("No job found for this UUID");
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
@@ -1,13 +0,0 @@
|
||||
#!/bin/bash
|
||||
# Query PostgreSQL monitor_jobs status
|
||||
# Using Rust code to execute SQL
|
||||
|
||||
echo "Jobs in PostgreSQL:"
|
||||
cat << 'SQL' > query_jobs.sql
|
||||
SELECT uuid, status, processors, created_at::date
|
||||
FROM monitor_jobs
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 10;
|
||||
SQL
|
||||
|
||||
echo "SQL query created. Need to execute via API or Rust..."
|
||||
@@ -1,10 +0,0 @@
|
||||
-- Delete failed face processor result to allow retry
|
||||
DELETE FROM processor_results
|
||||
WHERE job_id = 62
|
||||
AND processor = 'face'
|
||||
AND status = 'failed';
|
||||
|
||||
-- Check remaining processor_results for this job
|
||||
SELECT id, processor, status, retry_count
|
||||
FROM processor_results
|
||||
WHERE job_id = 62;
|
||||
+77
-150
@@ -1,178 +1,105 @@
|
||||
# Momentry Core Config Management
|
||||
# Momentry Core 配置管理
|
||||
|
||||
## Directory Structure
|
||||
## 目錄結構
|
||||
|
||||
```
|
||||
momentry_core_0.1/
|
||||
├── .env.example # Template (version controlled)
|
||||
├── .env # Local config (gitignored)
|
||||
├── .env.development # Playground dev overrides (gitignored)
|
||||
├── .env.local # Local overrides (gitignored)
|
||||
├── .env.example # 配置模板（已納入版本控制）
|
||||
├── .env # 本地配置（已從版本控制排除）
|
||||
├── .env.local # 本地覆蓋配置（已從版本控制排除）
|
||||
├── config/
|
||||
│ ├── README.md # This file
|
||||
│ └── port_registry.tsv # Central port registry
|
||||
└── src/core/config.rs # Config code with lazy_static env reading
|
||||
│ └── README.md # 本文件
|
||||
└── src/core/config.rs # 配置代碼
|
||||
```
|
||||
|
||||
## Load Order
|
||||
## 配置加載順序
|
||||
|
||||
For `momentry_playground` (development):
|
||||
1. `.env` — shared defaults
|
||||
2. `.env.development` — dev-specific overrides (loaded by playground binary)
|
||||
1. `.env` - 默認本地配置
|
||||
2. `.env.local` - 本地覆蓋（最高優先級）
|
||||
|
||||
For `momentry` (production):
|
||||
1. `.env` — production config
|
||||
## 環境變數列表
|
||||
|
||||
In Rust: `config.rs` reads env vars with lazy_static, falling back to hardcoded defaults.
|
||||
### 數據庫配置
|
||||
|
||||
## Environment Variables
|
||||
| 變數 | 說明 | 默認值 |
|
||||
|------|------|--------|
|
||||
| `DATABASE_URL` | PostgreSQL 連接字串 | `postgres://accusys@localhost:5432/momentry` |
|
||||
|
||||
### Server
|
||||
### Redis 配置
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `MOMENTRY_SERVER_PORT` | Server port (3002=prod, 3003=dev) | `3002` |
|
||||
| `MOMENTRY_REDIS_PREFIX` | Redis key prefix | `momentry:` (prod), `momentry_dev:` (dev) |
|
||||
| 變數 | 說明 | 默認值 |
|
||||
|------|------|--------|
|
||||
| `REDIS_URL` | Redis 連接字串 | `redis://:accusys@localhost:6379` |
|
||||
| `REDIS_PASSWORD` | Redis 密碼 | `accusys` |
|
||||
|
||||
### Database
|
||||
### 存儲路徑
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `DATABASE_URL` | PostgreSQL connection string | `postgres://accusys@localhost:5432/momentry` |
|
||||
| `DATABASE_SCHEMA` | Schema for dev isolation | `dev` |
|
||||
| `MONGODB_URL` | MongoDB connection string | `mongodb://localhost:27017` |
|
||||
| `MONGODB_DATABASE` | MongoDB database name | `momentry` (prod), `momentry_dev` (dev) |
|
||||
| `MONGODB_CACHE_ENABLED` | MongoDB cache toggle | `true` |
|
||||
| `MONGODB_CACHE_TTL_VIDEOS` | Cache TTL for videos | `300` |
|
||||
| `MONGODB_CACHE_TTL_SEARCH` | Cache TTL for search | `300` |
|
||||
| `MONGODB_CACHE_TTL_HYBRID_SEARCH` | Cache TTL for hybrid search | `600` |
|
||||
| `MONGODB_CACHE_TTL_VIDEO_META` | Cache TTL for video metadata | `3600` |
|
||||
| 變數 | 說明 | 默認值 |
|
||||
|------|------|--------|
|
||||
| `MOMENTRY_OUTPUT_DIR` | 輸出目錄 | `/Users/accusys/momentry/output` |
|
||||
| `MOMENTRY_BACKUP_DIR` | 備份目錄 | `/Users/accusys/momentry/backup/momentry` |
|
||||
| `MOMENTRY_SCRIPTS_DIR` | 腳本目錄 | `/Users/accusys/momentry_core_0.1/scripts` |
|
||||
| `MOMENTRY_PYTHON_PATH` | Python 路徑 | `/opt/homebrew/bin/python3.11` |
|
||||
|
||||
### Redis
|
||||
### 處理器超時（秒）
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `REDIS_URL` | Redis connection string | `redis://:accusys@localhost:6379` |
|
||||
| `REDIS_PASSWORD` | Redis password | `accusys` |
|
||||
| `REDIS_CACHE_TTL_HEALTH` | Health check cache TTL | `30` |
|
||||
| `REDIS_CACHE_TTL_VIDEO_META` | Video metadata cache TTL | `3600` |
|
||||
| 變數 | 說明 | 默認值 |
|
||||
|------|------|--------|
|
||||
| `MOMENTRY_ASR_TIMEOUT` | ASR 處理超時 | `3600` |
|
||||
| `MOMENTRY_CUT_TIMEOUT` | CUT 處理超時 | `3600` |
|
||||
| `MOMENTRY_DEFAULT_TIMEOUT` | 默認超時 | `7200` |
|
||||
|
||||
### Qdrant
|
||||
### 日誌
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `QDRANT_URL` | Qdrant server URL | `http://localhost:6333` |
|
||||
| `QDRANT_API_KEY` | Qdrant API key | `Test3200Test3200Test3200` |
|
||||
| `QDRANT_COLLECTION` | Collection name | `momentry_rule1` (prod), `momentry_dev_rule1_v2` (dev) |
|
||||
| 變數 | 說明 | 默認值 |
|
||||
|------|------|--------|
|
||||
| `RUST_LOG` | 日誌級別 | `info` |
|
||||
| `MOMENTRY_LOG_LEVEL` | 日誌級別（備選） | `info` |
|
||||
|
||||
### LLM
|
||||
## 使用方式
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `MOMENTRY_LLM_CHAT_URL` | Chat/function-calling endpoint | `http://127.0.0.1:8082/v1/chat/completions` |
|
||||
| `MOMENTRY_LLM_CHAT_MODEL` | Chat model name | `google_gemma-4-26B-A4B-it-Q5_K_M.gguf` |
|
||||
| `MOMENTRY_LLM_VISION_URL` | Vision LLM endpoint (E4B) | falls back to CHAT_URL |
|
||||
| `MOMENTRY_LLM_VISION_MODEL` | Vision model name (E4B) | falls back to CHAT_MODEL |
|
||||
| `MOMENTRY_LLM_SUMMARY_URL` | Summary LLM endpoint (5W1H) | falls back to CHAT_URL |
|
||||
| `MOMENTRY_LLM_SUMMARY_MODEL` | Summary model name | falls back to CHAT_MODEL |
|
||||
| `MOMENTRY_LLM_SUMMARY_ENABLED` | Toggle 5W1H summary generation | `true` |
|
||||
| `MOMENTRY_LLM_SUMMARY_TIMEOUT` | 5W1H timeout in seconds | `120` |
|
||||
| `MOMENTRY_LLM_CHAT_TIMEOUT` | Chat LLM timeout in seconds | `120` |
|
||||
| `MOMENTRY_LLM_VISION_TIMEOUT` | Vision LLM timeout in seconds | `120` |
|
||||
|
||||
### Embedding
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `MOMENTRY_EMBED_URL` | Embedding server URL | `http://localhost:11436` |
|
||||
|
||||
### TMDb Integration
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `TMDB_API_KEY` | TMDb API key (required for probe) | (none) |
|
||||
| `MOMENTRY_TMDB_PROBE_ENABLED` | Enable TMDb probe during register | `false` |
|
||||
|
||||
### Paths
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `MOMENTRY_OUTPUT_DIR` | Output directory for processing | `/Users/accusys/momentry/output` |
|
||||
| `MOMENTRY_BACKUP_DIR` | Backup directory | `/Users/accusys/momentry/backup/momentry` |
|
||||
| `MOMENTRY_SCRIPTS_DIR` | Python scripts directory | `/Users/accusys/momentry_core_0.1/scripts` |
|
||||
| `MOMENTRY_PYTHON_PATH` | Python interpreter path | `/opt/homebrew/bin/python3.11` |
|
||||
| `MOMENTRY_MEDIA_BASE_URL` | Base URL for media serving | (none) |
|
||||
|
||||
### Processor Timeouts
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `MOMENTRY_ASR_TIMEOUT` | ASR timeout in seconds | `3600` |
|
||||
| `MOMENTRY_CUT_TIMEOUT` | CUT timeout in seconds | `3600` |
|
||||
| `MOMENTRY_DEFAULT_TIMEOUT` | Default timeout in seconds | `7200` |
|
||||
|
||||
### Logging
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `RUST_LOG` | Rust log level (tracing) | `info` |
|
||||
| `MOMENTRY_LOG_LEVEL` | Fallback log level | `info` |
|
||||
|
||||
### Worker
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `MOMENTRY_WORKER_ENABLED` | Enable background worker | `true` |
|
||||
| `MOMENTRY_MAX_CONCURRENT` | Max concurrent jobs | `6` |
|
||||
| `MOMENTRY_POLL_INTERVAL` | Poll interval in seconds | `10` |
|
||||
| `MOMENTRY_WORKER_BATCH_SIZE` | Batch size | `5` |
|
||||
|
||||
### Synonym Expansion
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `MOMENTRY_SYNONYM_FILES` | Comma-separated paths to synonym JSON files | (none) |
|
||||
| `MOMENTRY_SYNONYM_FILE` | Single synonym file (deprecated) | (none) |
|
||||
|
||||
### Encryption
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `AUDIT_ENCRYPTION_KEY` | 32-byte hex encryption key (64 hex chars) | (none) |
|
||||
|
||||
## Port Registry
|
||||
|
||||
See `config/port_registry.tsv` for the authoritative list of all ports and their owners.
|
||||
|
||||
| Port | Service | Owner | Config Key |
|
||||
|------|---------|-------|------------|
|
||||
| 5432 | PostgreSQL | postgres | `DATABASE_URL` |
|
||||
| 6379 | Redis | redis-server | `REDIS_URL` |
|
||||
| 6333 | Qdrant | qdrant | `QDRANT_URL` |
|
||||
| 8082 | LLM Chat (A4B) | llama-server | `MOMENTRY_LLM_CHAT_URL` |
|
||||
| 8083 | LLM Vision (E4B) | llama-server | `MOMENTRY_LLM_VISION_URL` |
|
||||
| 11434 | Ollama | ollama | `MOMENTRY_OLLAMA_URL` |
|
||||
| 11436 | Embedding | embeddinggemma_server.py | `MOMENTRY_EMBED_URL` |
|
||||
| 27017 | MongoDB | mongod | `MONGODB_URL` |
|
||||
| 3002 | Production API | momentry | `MOMENTRY_SERVER_PORT` |
|
||||
| 3003 | Playground API | momentry_playground | `MOMENTRY_SERVER_PORT` |
|
||||
|
||||
## Quick Start
|
||||
### 1. 首次設置
|
||||
|
||||
```bash
|
||||
# 1. Copy template
|
||||
# 複製模板
|
||||
cp .env.example .env
|
||||
|
||||
# 2. Edit .env for production or use .env.development for playground
|
||||
# 3. Start all services
|
||||
./scripts/start_momentry.sh
|
||||
# 編輯配置
|
||||
nano .env
|
||||
```
|
||||
|
||||
## Version Control
|
||||
### 2. 本地覆蓋
|
||||
|
||||
| File | Tracked | Purpose |
|
||||
|------|---------|---------|
|
||||
| `.env.example` | ✅ Yes | Template with all options documented |
|
||||
| `.env` | ❌ No | Local sensitive config |
|
||||
| `.env.development` | ❌ No | Dev-specific overrides |
|
||||
| `.env.local` | ❌ No | Local overrides (highest priority) |
|
||||
創建 `.env.local` 設置僅本地適用的配置：
|
||||
|
||||
```bash
|
||||
# .env.local 示例
|
||||
DATABASE_URL=postgres://local:password@localhost:5432/momentry_dev
|
||||
MOMENTRY_LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
### 3. 運行應用
|
||||
|
||||
```bash
|
||||
# 加載配置並運行
|
||||
source .env && cargo run
|
||||
|
||||
# 或使用 direnv
|
||||
direnv allow
|
||||
```
|
||||
|
||||
## 版本控制策略
|
||||
|
||||
| 文件 | 版本控制 | 說明 |
|
||||
|------|---------|------|
|
||||
| `.env.example` | ✅ 追蹤 | 模板，包含所有選項 |
|
||||
| `.env` | ❌ 忽略 | 本地敏感配置 |
|
||||
| `.env.local` | ❌ 忽略 | 本地覆蓋配置 |
|
||||
|
||||
## 部署檢查清單
|
||||
|
||||
- [ ] 複製 `.env.example` 到 `.env`
|
||||
- [ ] 設置數據庫連接
|
||||
- [ ] 設置 Redis 密碼
|
||||
- [ ] 配置目錄路徑
|
||||
- [ ] 確認日誌級別
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
# Development Environment Configuration
|
||||
# Used by: momentry_playground binary on port 3003
|
||||
#
|
||||
# This file extracts development-specific variables from .env.development
|
||||
# Startup scripts must export these variables for Python subprocess inheritance
|
||||
|
||||
# Server Configuration
|
||||
MOMENTRY_SERVER_PORT=3003
|
||||
MOMENTRY_REDIS_PREFIX=momentry_dev:
|
||||
|
||||
# Database Schema
|
||||
DATABASE_SCHEMA=dev
|
||||
|
||||
# Output Directory (CRITICAL for Python scripts)
|
||||
MOMENTRY_OUTPUT_DIR=/Users/accusys/momentry/output_dev
|
||||
|
||||
# Backup Directory
|
||||
MOMENTRY_BACKUP_DIR=/Users/accusys/momentry/backup/momentry_dev
|
||||
|
||||
# Storage
|
||||
MOMENTRY_SFTP_ROOT=/Users/accusys/momentry/var/sftpgo/data/demo/
|
||||
|
||||
# Python Path (venv for development)
|
||||
MOMENTRY_PYTHON_PATH=/Users/accusys/momentry_core/venv/bin/python
|
||||
MOMENTRY_SCRIPTS_DIR=/Users/accusys/momentry_core/scripts
|
||||
|
||||
# Logging
|
||||
RUST_LOG=info
|
||||
MOMENTRY_LOG_LEVEL=info
|
||||
|
||||
# Worker Configuration
|
||||
MOMENTRY_WORKER_ENABLED=true
|
||||
MOMENTRY_MAX_CONCURRENT=6
|
||||
MOMENTRY_POLL_INTERVAL=10
|
||||
MOMENTRY_WORKER_BATCH_SIZE=5
|
||||
|
||||
# TMDb Integration
|
||||
TMDB_API_KEY=e9cde52197f6f8df4d9db99da93db1fb
|
||||
MOMENTRY_TMDB_PROBE_ENABLED=true
|
||||
|
||||
# LLM Configuration
|
||||
MOMENTRY_LLM_SUMMARY_URL=http://127.0.0.1:8000/v1/chat/completions
|
||||
MOMENTRY_LLM_SUMMARY_MODEL=gemma-4-E4B
|
||||
MOMENTRY_LLM_SUMMARY_ENABLED=true
|
||||
|
||||
# Embedding
|
||||
MOMENTRY_EMBED_URL=http://localhost:11436
|
||||
@@ -1,24 +0,0 @@
|
||||
# Port Registry - Momentry Core
|
||||
# Each port must have exactly one owner.
|
||||
# Before adding a service: pick a free port, add a row here, then configure.
|
||||
#
|
||||
# Port Service Owner Config Key Default Source
|
||||
22 ssh sshd - - macOS
|
||||
80 http Caddy - - Caddyfile
|
||||
443 https Caddy - - Caddyfile
|
||||
2019 caddy-admin Caddy - - Caddyfile (internal)
|
||||
3000 gitea gitea - 3000 start_momentry.sh
|
||||
3002 production momentry MOMENTRY_SERVER_PORT 3002 run-server-3002.sh
|
||||
3003 playground momentry_playground MOMENTRY_SERVER_PORT 3003 start_momentry.sh
|
||||
3200 dashboard Caddy - - Caddyfile
|
||||
3306 mariadb mariadbd - 3306 start_momentry.sh
|
||||
5432 postgresql postgres DATABASE_URL postgres://...:5432 start_momentry.sh
|
||||
6379 redis redis-server REDIS_URL redis://...:6379 start_momentry.sh
|
||||
6333 qdrant qdrant QDRANT_URL http://...:6333 start_momentry.sh
|
||||
8081 wordpress Caddy - - Caddyfile
|
||||
8082 llm-chat llama-server MOMENTRY_LLM_CHAT_URL http://...:8082 start_momentry.sh
|
||||
8083 llm-vision llama-server MOMENTRY_LLM_VISION_URL http://...:8083 start_momentry.sh
|
||||
9000 php-fpm php-fpm - 9000 brew services
|
||||
11434 ollama ollama MOMENTRY_OLLAMA_URL http://...:11434 start_momentry.sh
|
||||
11436 embedding embeddinggemma MOMENTRY_EMBED_URL http://...:11436 start_momentry.sh
|
||||
27017 mongodb mongod MONGODB_URL mongodb://...:27017 start_momentry.sh
|
||||
|
@@ -1,39 +0,0 @@
|
||||
# Production Environment Configuration
|
||||
# Used by: momentry binary on port 3002
|
||||
#
|
||||
# This file extracts production-specific variables from .env
|
||||
# Startup scripts must export these variables for Python subprocess inheritance
|
||||
|
||||
# Server Configuration
|
||||
MOMENTRY_SERVER_PORT=3002
|
||||
MOMENTRY_REDIS_PREFIX=momentry:
|
||||
|
||||
# Database Schema
|
||||
DATABASE_SCHEMA=public
|
||||
|
||||
# Output Directory (CRITICAL for Python scripts)
|
||||
MOMENTRY_OUTPUT_DIR=/Users/accusys/momentry/output
|
||||
|
||||
# Backup Directory
|
||||
MOMENTRY_BACKUP_DIR=/Users/accusys/momentry/backup/momentry
|
||||
|
||||
# Storage
|
||||
MOMENTRY_STORAGE_ROOT=/Users/accusys/momentry/var/sftpgo/data
|
||||
|
||||
# Python Path
|
||||
MOMENTRY_PYTHON_PATH=/opt/homebrew/bin/python3.11
|
||||
|
||||
# Logging
|
||||
RUST_LOG=debug
|
||||
MOMENTRY_LOG_LEVEL=debug
|
||||
|
||||
# Worker Configuration
|
||||
MOMENTRY_WORKER_ENABLED=true
|
||||
MOMENTRY_MAX_CONCURRENT=6
|
||||
MOMENTRY_POLL_INTERVAL=10
|
||||
MOMENTRY_WORKER_BATCH_SIZE=5
|
||||
MOMENTRY_FORCE_RETRY=true
|
||||
|
||||
# TMDb Integration
|
||||
TMDB_API_KEY=e9cde52197f6f8df4d9db99da93db1fb
|
||||
MOMENTRY_TMDB_PROBE_ENABLED=true
|
||||
@@ -1,123 +0,0 @@
|
||||
# Momentry Core Production Configuration
|
||||
# Version: 1.0.0
|
||||
# Effective: 2025-03-27
|
||||
|
||||
[server]
|
||||
host = "0.0.0.0"
|
||||
port = 3002
|
||||
workers = 4
|
||||
log_level = "info"
|
||||
max_connections = 1000
|
||||
keep_alive = 75
|
||||
|
||||
[database]
|
||||
url = "postgres://accusys@localhost:5432/momentry"
|
||||
pool_size = 20
|
||||
idle_timeout = 300
|
||||
max_lifetime = 1800
|
||||
|
||||
[redis]
|
||||
url = "redis://:accusys@localhost:6379"
|
||||
prefix = "momentry:"
|
||||
pool_size = 50
|
||||
connection_timeout = 5
|
||||
read_timeout = 3
|
||||
write_timeout = 3
|
||||
|
||||
[storage]
|
||||
output_dir = "/Users/accusys/momentry/output"
|
||||
backup_dir = "/Users/accusys/momentry/backup"
|
||||
max_file_size = "10GB"
|
||||
|
||||
[processors]
|
||||
asr_timeout = 7200 # 2 hours for long videos
|
||||
ocr_timeout = 3600 # 1 hour
|
||||
yolo_timeout = 14400 # 4 hours
|
||||
face_timeout = 3600 # 1 hour
|
||||
pose_timeout = 7200 # 2 hours
|
||||
asrx_timeout = 10800 # 3 hours for speaker diarization
|
||||
cut_timeout = 7200 # 2 hours for scene detection
|
||||
caption_timeout = 3600 # 1 hour for captioning
|
||||
story_timeout = 3600 # 1 hour for story generation
|
||||
default_timeout = 7200
|
||||
max_concurrent = 2 # Limit to prevent overload
|
||||
|
||||
[asr]
|
||||
model_size = "medium"
|
||||
device = "cpu"
|
||||
language = "auto"
|
||||
task = "transcribe"
|
||||
beam_size = 5
|
||||
best_of = 5
|
||||
|
||||
[ocr]
|
||||
languages = "en"
|
||||
confidence = 0.7
|
||||
gpu = false
|
||||
model_path = "~/.EasyOCR/model"
|
||||
|
||||
[yolo]
|
||||
model_size = "yolov8n.pt"
|
||||
confidence = 0.25
|
||||
iou = 0.45
|
||||
gpu = false
|
||||
auto_save_interval = 30
|
||||
auto_save_frames = 300
|
||||
classes = "" # empty = all classes
|
||||
|
||||
[face]
|
||||
method = "haar"
|
||||
confidence = 0.5
|
||||
min_size = 30
|
||||
max_size = 300
|
||||
scale_factor = 1.1
|
||||
min_neighbors = 3
|
||||
gpu = false
|
||||
gpu_backend = "cpu" # cpu, cuda, mps, rocm
|
||||
enable_mps = false
|
||||
|
||||
[pose]
|
||||
model_size = "yolov8n-pose.pt"
|
||||
confidence = 0.25
|
||||
iou = 0.45
|
||||
gpu = false
|
||||
keypoint_confidence = 0.5
|
||||
max_persons = 10
|
||||
|
||||
[asrx]
|
||||
model_size = "medium"
|
||||
device = "cpu"
|
||||
language = "en"
|
||||
batch_size = 16
|
||||
diarization = true
|
||||
min_speakers = 1
|
||||
max_speakers = 10
|
||||
|
||||
[cut]
|
||||
method = "content"
|
||||
threshold = 27.0
|
||||
min_scene_length = 0.5
|
||||
show_progress = true
|
||||
|
||||
[caption]
|
||||
model = "gpt-4"
|
||||
max_tokens = 1000
|
||||
temperature = 0.7
|
||||
|
||||
[story]
|
||||
model = "gpt-4"
|
||||
max_tokens = 2000
|
||||
temperature = 0.8
|
||||
|
||||
[audit]
|
||||
enabled = true
|
||||
log_file = "/Users/accusys/momentry/logs/audit.log"
|
||||
retention_days = 90
|
||||
|
||||
[monitoring]
|
||||
enabled = true
|
||||
metrics_port = 9090
|
||||
health_check_interval = 30
|
||||
alert_threshold_cpu = 80
|
||||
alert_threshold_memory = 85
|
||||
alert_threshold_disk = 90
|
||||
@@ -1,761 +0,0 @@
|
||||
# AGENTS.md - Momentry Core
|
||||
|
||||
Rust-based digital asset management system with video analysis and RAG capabilities.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ CRITICAL: 開發隔離原則
|
||||
|
||||
### 絕對禁止事項
|
||||
- **絕對不可修改 `/Users/accusys/wordpress/` 目錄下的任何檔案**
|
||||
- **絕對不可修改 n8n 工作流或設定**
|
||||
- **絕對不可修改 WordPress 或 n8n 的資料庫 table**
|
||||
- **除非是 release 作業，絕對不可動 port 3002 (production)**
|
||||
- **🔴 DELETE / REMOVE / DROP / CLEAR 任何資料前必須先問使用者「要刪嗎？」獲得明確同意後才能執行**
|
||||
- **🔴 Qdrant collection 刪除、DB truncate、檔案刪除、資料清空 — 一律要先問**
|
||||
- **🔴 不確定是否該刪 → 先問，不要自己決定**
|
||||
|
||||
### 開發範圍界定
|
||||
| 範圍 | 狀態 | 說明 |
|
||||
|------|------|------|
|
||||
| `momentry_core_0.1/` | ✅ **可開發** | Momentry Core 主要開發目錄 |
|
||||
| `momentry_core_0.1/portal/` | ✅ **可開發** | Tauri Portal 前端 |
|
||||
| `momentry_core_0.1/src/` | ✅ **可開發** | Rust 後端程式碼 |
|
||||
| `/Users/accusys/wordpress/` | ❌ **禁止修改** | WordPress/Marcom 團隊負責 |
|
||||
| n8n 工作流 | ❌ **禁止修改** | 自動化流程，與 dev 無關 |
|
||||
| WordPress/n8n 資料庫 table | ❌ **禁止修改** | Marcom 團隊管理，與 dev 無關 |
|
||||
|
||||
### 開發環境
|
||||
| 服務 | Port | 用途 | 命令 |
|
||||
|------|------|------|------|
|
||||
| Playground | 3003 | **唯一開發環境** | `cargo run --bin momentry_playground -- server` |
|
||||
| Production | 3002 | ❌ 禁止修改 | `cargo run -- server` (僅 release 時) |
|
||||
| Portal (Tauri) | 1420 | 前端開發 | `npm run tauri dev` |
|
||||
|
||||
## ⚠️ 交叉污染防制 (Cross-Contamination Prevention)
|
||||
|
||||
**每個執行前必須評估是否會汙染其他獨立作業。**
|
||||
|
||||
### Scope Isolation Matrix
|
||||
|
||||
| 執行內容 | 允許的 Scope | 禁止影響 | 檢查事項 |
|
||||
|----------|-------------|----------|----------|
|
||||
| M4 delivery binary | `target/release/momentry` | Playground (3003), Production (3002) | 確認舊 process 未被誤殺 |
|
||||
| Playground server | `localhost:3003`, `dev.*` schema | Production (3002), `public.*` schema | `DATABASE_SCHEMA=dev` |
|
||||
| Production deploy | `localhost:3002`, `public.*` schema | Playground (3003), `dev.*` schema | 先停 production，不影響 playground |
|
||||
| Git commit | 只包含意圖修改的檔案 | 無關的 untracked files | `git status` 確認 stage 內容正確 |
|
||||
| CI / packaged tests | 測試環境 | 正式資料 | 測試用 DB 不能連到 production |
|
||||
| Doc changes | 指定文件 | 其他文件、程式碼 | `git diff --stat` 檢查 scope |
|
||||
| SQL migration | 目標 schema | 其他 schema、無關 table | `WHERE` clause 要精準 |
|
||||
| `sed` / `grep` / mass edit | 目標檔案集 | 非目標檔案 | 先用 `grep -c` 確認只有目標檔案匹配 |
|
||||
|
||||
### Recent Violations / Near-Misses
|
||||
|
||||
| 事件 | 問題 | 防止方式 |
|
||||
|------|------|----------|
|
||||
| `sed` API doc 編號 | `sed -i '' 's/.../.../g'` 改到所有行 | 先 `grep -c` 確認匹配，`git diff` 再提交 |
|
||||
| 亂加 `/api/v1/register` route | 不必要的 API 別名，汙染路由表 | 角色切換：路由設計不該由實作方決定 |
|
||||
| `API_WORKSPACE/` vs `GUIDES/` vs `REFERENCE/` vs `DESIGN/` vs `OPERATIONS/` vs `INTEGRATIONS/` | 文件放到錯誤分類 | API 文件改在 API_WORKSPACE/modules/ 編輯，`make deploy` 生成到 GUIDES/ |
|
||||
| Build release binary in plan mode | 浪費時間，無意義 | 嚴格遵守 plan/build mode 規定 |
|
||||
|
||||
### ⛔ 嚴格測試隔離規則 (Strict Test Isolation)
|
||||
- **所有測試 (Test) 必須在 Dev (3003) 進行**。
|
||||
- **絕對禁止 (ABSOLUTELY FORBIDDEN)** 在任何測試指令、Demo 流程或 API 檢查中使用 `localhost:3002`。
|
||||
- 即使是「測試 Unregister」或「檢查版本」，若未明確標示為 "Production Deployment"，一律視為違規。
|
||||
- **預設行為**: 所有 curl, CLI, 或程式碼測試指令，預設 URL 必須為 `http://localhost:3003`。
|
||||
|
||||
### 違反後果
|
||||
- 修改 WordPress/n8n 可能影響 marcom 團隊工作與生產環境
|
||||
- 修改 WordPress/n8n 資料庫 table 可能破壞自動化流程與資料完整性
|
||||
- 修改 port 3002 可能中斷正在使用的服務 (這是非常嚴重的錯誤)
|
||||
- 所有 dev 測試必須在 playground (3003) 進行
|
||||
|
||||
---
|
||||
|
||||
## AI Coding Principles (Karpathy-Inspired)
|
||||
|
||||
Behavioral guidelines to reduce common LLM coding mistakes.
|
||||
Source: [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) (94K stars)
|
||||
|
||||
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
|
||||
|
||||
### 1. Think Before Coding
|
||||
|
||||
**Don't assume. Don't hide confusion. Surface tradeoffs.**
|
||||
|
||||
- State your assumptions explicitly. If uncertain, ask.
|
||||
- If multiple interpretations exist, present them - don't pick silently.
|
||||
- If a simpler approach exists, say so. Push back when warranted.
|
||||
- If something is unclear, stop. Name what's confusing. Ask.
|
||||
|
||||
### 2. Simplicity First
|
||||
|
||||
**Minimum code that solves the problem. Nothing speculative.**
|
||||
|
||||
- No features beyond what was asked.
|
||||
- No abstractions for single-use code.
|
||||
- No "flexibility" or "configurability" that wasn't requested.
|
||||
- No error handling for impossible scenarios.
|
||||
- If you write 200 lines and it could be 50, rewrite it.
|
||||
|
||||
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
|
||||
|
||||
### 3. Surgical Changes
|
||||
|
||||
**Touch only what you must. Clean up only your own mess.**
|
||||
|
||||
When editing existing code:
|
||||
- Don't "improve" adjacent code, comments, or formatting.
|
||||
- Don't refactor things that aren't broken.
|
||||
- Match existing style, even if you'd do it differently.
|
||||
- If you notice unrelated dead code, mention it - don't delete it.
|
||||
|
||||
When your changes create orphans:
|
||||
- Remove imports/variables/functions that YOUR changes made unused.
|
||||
- Don't remove pre-existing dead code unless asked.
|
||||
|
||||
The test: Every changed line should trace directly to the user's request.
|
||||
|
||||
### 4. Goal-Driven Execution
|
||||
|
||||
**Define success criteria. Loop until verified.**
|
||||
|
||||
Transform tasks into verifiable goals:
|
||||
- "Add validation" -> "Write tests for invalid inputs, then make them pass"
|
||||
- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
|
||||
- "Refactor X" -> "Ensure tests pass before and after"
|
||||
|
||||
For multi-step tasks, state a brief plan:
|
||||
```
|
||||
1. [Step] -> verify: [check]
|
||||
2. [Step] -> verify: [check]
|
||||
3. [Step] -> verify: [check]
|
||||
```
|
||||
|
||||
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
|
||||
|
||||
---
|
||||
|
||||
These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
|
||||
|
||||
---
|
||||
|
||||
## Terminology (V4.0)
|
||||
|
||||
| Term | Scope | Description | Example |
|
||||
|------|-------|-------------|---------|
|
||||
| **file_uuid** | Video file | Video file identifier (renamed from `video_uuid`) | `384b0ff44aaaa1f1` |
|
||||
| **identity_uuid** | Global identity | Global person identity (cross-file) | `a9a90105-6d6b-46ff-92da-0c3c1a57dff4` |
|
||||
| **face_id** | Single detection | Single face detection (frame-level) | `face_100` |
|
||||
| **trace_id** | Face tracking | Face tracking ID (Face Tracker output) | `2` |
|
||||
| **chunk_id** | Sentence chunk | Sentence chunk (from pre_chunks via rules) | `chunk_1` |
|
||||
| **speaker_id** | Speaker segment | Speaker ID (from ASRX) | `SPEAKER_0` |
|
||||
| **person_id** | ❌ **Deprecated** | Video-local person ID (removed in V4.0) | - |
|
||||
|
||||
### Architecture (V4.0)
|
||||
|
||||
```
|
||||
Face → Identity (Two-layer, direct binding)
|
||||
↓
|
||||
person_identities table: REMOVED
|
||||
file_identities table: ADDED (N:N relationship)
|
||||
```
|
||||
|
||||
### Key Changes (V3.x → V4.0)
|
||||
|
||||
| Change | V3.x | V4.0 |
|
||||
|--------|------|------|
|
||||
| **video_uuid** | Used everywhere | **file_uuid** |
|
||||
| **person_identities** | Required (303 records) | **Removed** |
|
||||
| **person_id APIs** | 28 endpoints | **Removed** (except register/bind) |
|
||||
| **Face binding** | Person → Identity | **Face → Identity** (direct) |
|
||||
| **Chunk binding** | Manual | **Auto** (time alignment) |
|
||||
|
||||
---
|
||||
|
||||
## Build & Run Commands
|
||||
|
||||
```bash
|
||||
# Build project (use debug builds for development/testing)
|
||||
cargo build
|
||||
cargo build --bin momentry
|
||||
cargo build --bin momentry_playground
|
||||
|
||||
# Build all binaries
|
||||
cargo build --bins
|
||||
|
||||
# Run CLI
|
||||
cargo run -- --help
|
||||
cargo run -- register /path/to/video.mp4
|
||||
cargo run -- server --host 0.0.0.0 --port 3002
|
||||
|
||||
# Run playground (development binary)
|
||||
cargo run --bin momentry_playground -- server
|
||||
cargo run --bin momentry_playground -- --help
|
||||
```
|
||||
|
||||
### ⚠️ CRITICAL: `cargo build --release` PROHIBITION
|
||||
- **NEVER run `cargo build --release` unless the user explicitly says "release the binary" or "正式 release"**
|
||||
- `cargo build --release` is SLOW and only needed when producing a production binary for deployment
|
||||
- For all development, testing, debugging, and linting: use `cargo build` or `cargo check`
|
||||
- If uncertain, ALWAYS ask the user first
|
||||
|
||||
## Binaries
|
||||
|
||||
| Binary | Purpose | Port | Redis Prefix | Environment |
|
||||
|--------|---------|------|--------------|-------------|
|
||||
| `momentry` | Production | 3002 | `momentry:` | `.env` |
|
||||
| `momentry_playground` | Development | 3003 | `momentry_dev:` | `.env.development` |
|
||||
| `momentry_player` | Video player | - | - | - |
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
cargo test
|
||||
|
||||
# Run single test by name
|
||||
cargo test test_name
|
||||
|
||||
# Run with output
|
||||
cargo test -- --nocapture
|
||||
|
||||
# Doc tests
|
||||
cargo test --doc
|
||||
```
|
||||
|
||||
## Linting & Formatting
|
||||
|
||||
```bash
|
||||
# Format code (edition=2021, max_width=100, tab_spaces=4)
|
||||
cargo fmt
|
||||
cargo fmt -- --check
|
||||
|
||||
# Lint
|
||||
cargo clippy
|
||||
cargo clippy --all-features
|
||||
|
||||
# Check for errors
|
||||
cargo check
|
||||
cargo check --all-features
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
### General
|
||||
- Use Rust 2021 edition
|
||||
- Use tracing for logging (not println!)
|
||||
- Keep lines under 100 characters
|
||||
|
||||
### Imports (order: std → external → local)
|
||||
```rust
|
||||
use std::path::Path;
|
||||
use anyhow::{Context, Result};
|
||||
use async_trait::async_trait;
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::core::chunk::Chunk;
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
- Use `anyhow::Result<T>` for application code
|
||||
- Use `thiserror` for library code
|
||||
- Use `.context()` for error context
|
||||
- Use `anyhow::bail!()` for early returns
|
||||
|
||||
```rust
|
||||
fn example() -> Result<SomeType> {
|
||||
let output = Command::new("ffprobe")
|
||||
.args([...])
|
||||
.output()
|
||||
.context("Failed to run ffprobe")?;
|
||||
|
||||
if !output.status.success() {
|
||||
anyhow::bail!("Command failed");
|
||||
}
|
||||
Ok(result)
|
||||
}
|
||||
```
|
||||
|
||||
### Naming
|
||||
- Types/Enums: PascalCase (`VideoRecord`, `ChunkType`)
|
||||
- Functions/Variables: snake_case (`get_video_by_uuid`)
|
||||
- Traits: PascalCase with -er suffix (`Database`, `ChunkStore`)
|
||||
- Files: snake_case (`postgres_db.rs`)
|
||||
|
||||
### Types
|
||||
- Use `serde::{Deserialize, Serialize}` for serializable types
|
||||
- Use `#[serde(rename_all = "snake_case")]` for enum variants
|
||||
- Use explicit numeric types (i64, u32, f64)
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct VideoRecord {
|
||||
pub id: i64,
|
||||
pub uuid: String,
|
||||
pub duration: f64,
|
||||
pub width: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
pub enum ChunkType {
|
||||
TimeBased,
|
||||
Sentence,
|
||||
Cut,
|
||||
}
|
||||
```
|
||||
|
||||
### Async Programming
|
||||
- Use `tokio` runtime with full features
|
||||
- Use `#[async_trait]` for async trait methods
|
||||
|
||||
```rust
|
||||
#[async_trait]
|
||||
pub trait Database: Send + Sync {
|
||||
async fn init() -> Result<Self>
|
||||
where Self: Sized;
|
||||
}
|
||||
```
|
||||
|
||||
## Code Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── main.rs # CLI entry point
|
||||
├── lib.rs # Library exports
|
||||
├── core/
|
||||
│ ├── api_key/ # API key management (anomaly, blacklist, encryption, etc.)
|
||||
│ ├── chunk/ # Chunking logic
|
||||
│ ├── config.rs # Centralized configuration (env vars)
|
||||
│ ├── db/ # Database (PostgreSQL, MongoDB, Redis, Qdrant)
|
||||
│ ├── embedding/ # Vector embeddings
|
||||
│ ├── overlay/ # Video overlay
|
||||
│ ├── probe/ # ffprobe integration
|
||||
│ ├── processor/ # ASR, OCR, YOLO, Face, Pose, CUT, ASRX
|
||||
│ │ └── executor.rs # Unified Python script executor
|
||||
│ ├── storage/ # File management
|
||||
│ └── thumbnail/ # Thumbnail extraction
|
||||
├── api/ # HTTP API (axum)
|
||||
├── player/ # Video player
|
||||
├── ui/ # TUI components
|
||||
└── watcher/ # File system watcher
|
||||
```
|
||||
|
||||
## Key Dependencies
|
||||
|
||||
- **Error handling**: `anyhow`, `thiserror`
|
||||
- **Async**: `tokio` (full features), `async-trait`
|
||||
- **CLI**: `clap` (derive)
|
||||
- **Serialization**: `serde`, `serde_json`, `chrono`
|
||||
- **Database**: `sqlx`, `mongodb`, `redis` (1.0), `qdrant-client`
|
||||
- **HTTP**: `axum`, `tower`
|
||||
- **Logging**: `tracing`, `tracing-subscriber`
|
||||
- **Config**: `once_cell` (lazy static config)
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Server
|
||||
- `MOMENTRY_SERVER_PORT` - API server port (default: `3002` for production, `3003` for playground)
|
||||
- `MOMENTRY_REDIS_PREFIX` - Redis key prefix (default: `momentry:` for production, `momentry_dev:` for playground)
|
||||
- `MOMENTRY_API_KEY` - API key for Player online mode testing
|
||||
|
||||
### Testing API Key
|
||||
```bash
|
||||
export MOMENTRY_API_KEY="muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
|
||||
|
||||
# Test Player online mode
|
||||
cargo run --features player --bin momentry_player -- -o
|
||||
```
|
||||
|
||||
### Database
|
||||
- `DATABASE_URL` - PostgreSQL (default: `postgres://accusys@localhost:5432/momentry`)
|
||||
|
||||
### Redis
|
||||
- `REDIS_URL` - Redis URL (default: `redis://:accusys@localhost:6379`)
|
||||
- `REDIS_PASSWORD` - Redis password (default: `accusys`)
|
||||
|
||||
### Paths
|
||||
- `MOMENTRY_OUTPUT_DIR` - Output directory (default: `/Users/accusys/momentry/output`)
|
||||
- `MOMENTRY_BACKUP_DIR` - Backup directory
|
||||
- `MOMENTRY_PYTHON_PATH` - Python path (default: `/opt/homebrew/bin/python3.11`)
|
||||
- `MOMENTRY_SCRIPTS_DIR` - Scripts directory
|
||||
|
||||
### Processor Timeouts
|
||||
- `MOMENTRY_ASR_TIMEOUT` - ASR timeout in seconds (default: 3600)
|
||||
- `MOMENTRY_CUT_TIMEOUT` - CUT timeout in seconds (default: 3600)
|
||||
- `MOMENTRY_DEFAULT_TIMEOUT` - Default timeout (default: 7200)
|
||||
|
||||
### TMDb Integration (Face Clustering)
|
||||
- `TMDB_API_KEY` - TMDb API key for movie metadata lookup (required for `MOMENTRY_TMDB_PROBE_ENABLED=true`)
|
||||
- `MOMENTRY_TMDB_PROBE_ENABLED` - Enable TMDb probe during registration (default: `false`)
|
||||
- Register phase: searches TMDb by filename, creates identities with tmdb_id/tmdb_profile
|
||||
- Post-process phase: matches detected faces against TMDb identities via cosine similarity
|
||||
|
||||
### Synonym Expansion
|
||||
- `MOMENTRY_SYNONYM_FILES` - Comma-separated paths to synonym JSON files (e.g., `data/english_synonyms.json,data/llm_synonyms.json`)
|
||||
- `MOMENTRY_SYNONYM_FILE` - Single synonym JSON file path (deprecated, use above)
|
||||
|
||||
### Logging
|
||||
- `RUST_LOG` or `MOMENTRY_LOG_LEVEL` - Log level (default: `info`)
|
||||
|
||||
## Notes
|
||||
|
||||
- Unit tests exist (86 library tests)
|
||||
- Video processing uses external tools (ffprobe, Python scripts)
|
||||
- Multi-database architecture (PostgreSQL, MongoDB, Redis, Qdrant)
|
||||
- Monitor directory is a separate system (not Rust)
|
||||
- PythonExecutor provides unified script execution with timeout support
|
||||
- Redis 1.0.x for improved performance
|
||||
- FaceNet CoreML model (`models/facenet512.mlpackage`) replaces InsightFace for embedding extraction (MIT license, ANE-accelerated)
|
||||
|
||||
### LLM Synonym Generation
|
||||
|
||||
Generate synonym database using llama.cpp (Gemma4):
|
||||
|
||||
```bash
|
||||
# Generate full database (162 entries, ~5 minutes)
|
||||
python3 scripts/generate_synonyms_llamacpp.py
|
||||
|
||||
# Quick test
|
||||
python3 scripts/generate_synonyms_llamacpp.py --test
|
||||
|
||||
# Resume from existing file
|
||||
python3 scripts/generate_synonyms_llamacpp.py --resume
|
||||
|
||||
# Output: data/llm_synonyms.json (27 Chinese + 135 English words)
|
||||
```
|
||||
|
||||
## Task Management
|
||||
|
||||
### 使用 todowrite 追蹤任務
|
||||
```bash
|
||||
# 創建任務清單
|
||||
/todo 建立配置模組 [in_progress]
|
||||
/todo 添加單元測試 [pending]
|
||||
|
||||
# 更新狀態
|
||||
/todo 完成標記 [completed]
|
||||
```
|
||||
|
||||
### 任務批次建議
|
||||
- 一次處理 1-2 個功能
|
||||
- 每個功能完成後驗證 (clippy + test)
|
||||
- 驗證通過後再繼續下一個
|
||||
|
||||
## Code Review Checklist
|
||||
|
||||
完成任務後檢查：
|
||||
- [ ] `cargo clippy --lib` 通過
|
||||
- [ ] `cargo test --lib` 通過
|
||||
- [ ] `cargo fmt -- --check` 通過
|
||||
- [ ] 文檔已更新 (如需要)
|
||||
- [ ] 新功能有單元測試
|
||||
|
||||
## Commit Guidelines
|
||||
|
||||
```bash
|
||||
# feat: 新功能
|
||||
git commit -m "feat: add monitor_jobs table"
|
||||
|
||||
# fix: 錯誤修復
|
||||
git commit -m "fix: resolve SQL injection in store_vector"
|
||||
|
||||
# refactor: 重構
|
||||
git commit -m "refactor: use parameterized queries"
|
||||
|
||||
# docs: 文檔更新
|
||||
git commit -m "docs: update AGENTS.md with new modules"
|
||||
```
|
||||
|
||||
## Pre-commit Hook
|
||||
|
||||
專案已配置 `.git/hooks/pre-commit`，提交前自動檢查：
|
||||
|
||||
```bash
|
||||
# 檢查內容
|
||||
1. cargo fmt --check # Rust 格式化檢查
|
||||
2. cargo clippy --lib # Rust Lint 檢查
|
||||
3. cargo test --lib # Rust 單元測試
|
||||
4. ruff check # Python Lint 檢查
|
||||
5. ruff format --check # Python 格式化檢查
|
||||
6. markdownlint # Markdown 格式檢查
|
||||
7. shellcheck # Shell 腳本檢查
|
||||
|
||||
# 跳過檢查（不建議）
|
||||
git commit --no-verify
|
||||
|
||||
# 跳過特定檢查
|
||||
git commit --skip-checks
|
||||
```
|
||||
|
||||
**注意**: Hook 僅檢查已暫存的 Rust/Python/Markdown 文件。
|
||||
|
||||
### Python 環境設置
|
||||
```bash
|
||||
# 安裝 ruff
|
||||
pip install ruff==0.11.2
|
||||
|
||||
# 格式化 Python 文件
|
||||
ruff format scripts/
|
||||
|
||||
# Lint Python 文件
|
||||
ruff check scripts/
|
||||
```
|
||||
|
||||
### Markdown 環境設置
|
||||
```bash
|
||||
# 安裝 markdownlint-cli (使用系統 Node.js)
|
||||
npm install -g markdownlint-cli
|
||||
|
||||
# 檢查 Markdown 文件
|
||||
markdownlint docs/
|
||||
|
||||
# 配置檔案
|
||||
.markdownlint.json
|
||||
```
|
||||
|
||||
### Shell 環境設置
|
||||
```bash
|
||||
# 安裝 shellcheck
|
||||
brew install shellcheck
|
||||
|
||||
# 檢查 Shell 腳本
|
||||
shellcheck scripts/*.sh monitor/**/*.sh
|
||||
```
|
||||
|
||||
**注意**: Hook 只檢查 error 等級的 shellcheck 問題，style 警告會顯示但不阻擋提交。
|
||||
|
||||
## Release Workflow
|
||||
|
||||
### Release 前準備
|
||||
每次 release production binary 前，必須：
|
||||
|
||||
1. **建立 Release Tag**
|
||||
```bash
|
||||
git tag -a v0.X.X -m "Release vX.X.X - YYYY-MM-DD"
|
||||
git push origin v0.X.X
|
||||
```
|
||||
|
||||
2. **備份獨立 Source Code**
|
||||
```bash
|
||||
# 建立 release 獨立目錄
|
||||
RELEASE_DIR="/Users/accusys/momentry_core_releases/v0.X.X"
|
||||
mkdir -p "$RELEASE_DIR"
|
||||
|
||||
# 複製完整原始碼（排除不必要的檔案）
|
||||
rsync -av --exclude='.git' --exclude='target' --exclude='node_modules' \
|
||||
/Users/accusys/momentry_core_0.1/ "$RELEASE_DIR/"
|
||||
|
||||
# 記錄 release 資訊
|
||||
echo "Release: v0.X.X" > "$RELEASE_DIR/RELEASE_INFO.txt"
|
||||
echo "Date: $(date)" >> "$RELEASE_DIR/RELEASE_INFO.txt"
|
||||
echo "Git Commit: $(git rev-parse HEAD)" >> "$RELEASE_DIR/RELEASE_INFO.txt"
|
||||
echo "Binary: $(ls -la target/release/momentry)" >> "$RELEASE_DIR/RELEASE_INFO.txt"
|
||||
```
|
||||
|
||||
3. **備份 Binary**
|
||||
```bash
|
||||
cp target/release/momentry "$RELEASE_DIR/momentry_v0.X.X"
|
||||
cp target/release/momentry_playground "$RELEASE_DIR/momentry_playground_v0.X.X" 2>/dev/null
|
||||
```
|
||||
|
||||
4. **記錄資料庫 Schema**
|
||||
```bash
|
||||
pg_dump -U accusys -d momentry --schema-only > "$RELEASE_DIR/schema_v0.X.X.sql"
|
||||
```
|
||||
|
||||
### 重要性
|
||||
- 避免 release binary 與 current source code 不一致
|
||||
- 方便追蹤特定 release 的程式碼狀態
|
||||
- 必要時可快速復原或比對差異
|
||||
- 確保資料庫 schema 與程式碼版本對應
|
||||
|
||||
## Reference Documents
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `docs/OPENCODE_GUIDE.md` | OpenCode 使用規範 |
|
||||
| `docs/ARCHITECTURE_EVALUATION.md` | 架構優化待評估項目 (含 GraphRAG) |
|
||||
| `docs/PENDING_ISSUES.md` | 待解決問題追蹤 |
|
||||
| `docs/MOMENTRY_CORE_MONITORING.md` | 監控系統規範 |
|
||||
| `docs/MOMENTRY_CORE_REDIS_KEYS.md` | Redis Key 設計規範 |
|
||||
| `docs/PYTHON.md` | Python 腳本規範 |
|
||||
| `docs/FILE_CHANGE_MANAGEMENT.md` | 文件修改管理規範 |
|
||||
| `docs/YOLO_RESUME_INTEGRATION.md` | YOLO Resume 功能整合記錄 |
|
||||
| `docs/DOCUMENT_EMBEDDING_STRATEGY.md` | Parent-Child 嵌入策略 |
|
||||
| `docs/PROCESSING_PIPELINE.md` | 處理流程文檔 |
|
||||
| `docs/N8N_DEMO_WORKFLOW.md` | n8n 工作流文檔 |
|
||||
| `docs/FRESH_MAC_INSTALLATION.md` | 全新 Mac 安裝指南 |
|
||||
| `docs/SERVICES.md` | 服務總覽與管理 |
|
||||
| `docs/SFTPGO_DEMO_USER.md` | SFTPGo 用戶指南 |
|
||||
|
||||
## Document Change Workflow
|
||||
|
||||
修改文件前請參考 `docs/FILE_CHANGE_MANAGEMENT.md`，確保：
|
||||
|
||||
1. **修改前**：完整閱讀文件、執行預檢清單
|
||||
2. **修改中**：提供變更計畫、取得確認
|
||||
3. **修改後**：展示 diff、更新版本歷史
|
||||
4. **驗證**：執行 lint/test、提交前審查
|
||||
|
||||
### AI 工具修改規範
|
||||
|
||||
AI 工具修改文件時：
|
||||
- 必須先完整閱讀文件（不可只讀取部分章節）
|
||||
- 修改前先提出變更計畫供確認
|
||||
- 修改後展示 diff 內容
|
||||
- 更新版本歷史表
|
||||
|
||||
## PHP Development
|
||||
|
||||
WordPress 作為 Momentry Portal，負責 n8n 自動化與 sftpgo 檔案服務的頁面整合。
|
||||
|
||||
### 編輯器設定
|
||||
|
||||
| 編輯器 | LSP 方案 | 安裝方式 |
|
||||
|--------|----------|----------|
|
||||
| VS Code | Intelephense | Extension Marketplace (推薦) |
|
||||
| Cursor | Intelephense | Extension Marketplace (推薦) |
|
||||
| CLI | phpactor | `~/bin/phpactor` |
|
||||
|
||||
### Intelephense (VS Code/Cursor)
|
||||
|
||||
1. 安裝 Extension: 搜尋 "Intelephense"
|
||||
2. 設定:
|
||||
```json
|
||||
{
|
||||
"intelephense.stubs": ["wordpress"]
|
||||
}
|
||||
```
|
||||
|
||||
### phpactor (CLI)
|
||||
|
||||
```bash
|
||||
# 安裝方式
|
||||
brew install composer
|
||||
curl -sSL https://github.com/phpactor/phpactor/releases/latest/download/phpactor.phar -o ~/bin/phpactor
|
||||
chmod +x ~/bin/phpactor
|
||||
|
||||
# 安裝 WordPress Stubs
|
||||
cd /Users/accusys/wordpress/web
|
||||
composer require --dev php-stubs/wordpress-stubs
|
||||
|
||||
# 建立 WordPress 索引
|
||||
cd /Users/accusys/wordpress/web
|
||||
~/bin/phpactor index:build --reset
|
||||
|
||||
# 常用指令
|
||||
~/bin/phpactor class:search "WP_User" # 搜尋類別
|
||||
~/bin/phpactor index:query WP_User # 查看類別資訊
|
||||
~/bin/phpactor navigate /path/to/file.php # 導航到定義
|
||||
```
|
||||
|
||||
### WordPress 程式碼位置
|
||||
| 類型 | 路徑 |
|
||||
|------|------|
|
||||
| 主題 | `/Users/accusys/wordpress/web/wp-content/themes/` |
|
||||
| 插件 | `/Users/accusys/wordpress/web/wp-content/plugins/` |
|
||||
|
||||
### 與 marcom 團隊協作
|
||||
| 角色 | 負責 |
|
||||
|------|------|
|
||||
| marcom 團隊 | Figma 設計 / Elementor 建構 |
|
||||
| OpenCode | 程式碼實作 / 重構 |
|
||||
|
||||
### 開發時程
|
||||
```
|
||||
Phase 1: marcom 建構 (現在) → Elementor 頁面建構
|
||||
Phase 2: 交付審視 (TBD) → 功能確認 / 重構評估
|
||||
Phase 3: OpenCode 重構 → 純程式碼實作，交付無 Elementor 依賴版本
|
||||
```
|
||||
|
||||
## M4 通知規範
|
||||
|
||||
### 固定通知方式
|
||||
|
||||
通知 M4 的唯一管道：**`M4_workspace/` 下建立回覆文件 + `git commit`**。不需口頭、即時訊息、郵件。
|
||||
|
||||
### 命名規則
|
||||
|
||||
```
|
||||
docs_v1.0/M4_workspace/YYYY-MM-DD_<topic>_response.md (回覆 M4 問題)
|
||||
docs_v1.0/M4_workspace/YYYY-MM-DD_<topic>.md (主動通報)
|
||||
docs_v1.0/M4_workspace/YYYY-MM-DD_<topic>_test_report.md (測試報告)
|
||||
```
|
||||
|
||||
### 觸發時機
|
||||
|
||||
| 情境 | 動作 |
|
||||
|------|------|
|
||||
| M4 提交問題報告到 `M4_workspace/` | 修復後，回覆 `*_response.md` |
|
||||
| 完成 M4 要求的任務 | 回覆 `*_response.md` |
|
||||
| 重大變更（模型替換、架構變更） | 主動通知 `*.md` |
|
||||
| 新測試包產出 | `*_test_report.md` |
|
||||
|
||||
### 交付檢查
|
||||
|
||||
1. 文件寫入 `docs_v1.0/M4_workspace/`
|
||||
2. `git add` 包含該文件
|
||||
3. `git commit` 含相關變更
|
||||
4. M4 透過 git log 查看
|
||||
|
||||
詳細規範見 `docs_v1.0/M4_workspace/M4_NOTIFICATION_PROTOCOL.md`。
|
||||
|
||||
## UUID Naming Rule
|
||||
|
||||
**Never use bare `uuid` in API route paths, query params, JSON keys, or code variable names. Always qualify:**
|
||||
|
||||
| Context | Must use | Never |
|
||||
|---------|----------|-------|
|
||||
| Video/file resource | `file_uuid` | `uuid` |
|
||||
| Identity resource | `identity_uuid` | `uuid` |
|
||||
| Query parameter | `file_uuid=`, `identity_uuid=` | `uuid=` |
|
||||
| Route path | `:file_uuid`, `:identity_uuid` | `:uuid` |
|
||||
| JSON key | `"file_uuid"`, `"identity_uuid"` | `"uuid"` |
|
||||
|
||||
This applies to docs, code, API responses, and curl examples. Exceptions: internal database primary key names (e.g. `identities.uuid` column).
|
||||
|
||||
## Document Compliance Checklist
|
||||
|
||||
Before creating any file in `docs_v1.0/` (API_WORKSPACE, GUIDES, REFERENCE, DESIGN, OPERATIONS, INTEGRATIONS), verify all items below.
|
||||
**IMPORTANT**: API functional documents are generated from `API_WORKSPACE/modules/`. Edit modules there, then run `make deploy` in `API_WORKSPACE/` to update `GUIDES/`. Never edit generated files in `GUIDES/` directly. See `DESIGN/Modular_Doc_System_V1.0.md` for the full system design.
|
||||
|
||||
### P0 — Mandatory (7 items)
|
||||
|
||||
| # | Check | Rule |
|
||||
|---|-------|------|
|
||||
| 1 | YAML frontmatter | `title`, `version`, `date`, `author`, `status` present |
|
||||
| 2 | Version history | Table at bottom of file tracking changes |
|
||||
| 3 | Top info table | scope, status, applicable to, etc. |
|
||||
| 4 | PascalCase filename | e.g. `DetectorRegistry.md`, not `detector_registry.md` |
|
||||
| 5 | `_` separator | Within filenames use `_`, never spaces or other chars |
|
||||
| 6 | English content | Entire file in English |
|
||||
| 7 | Correct directory | File must reside in appropriate directory: `API_WORKSPACE/modules/` (API endpoint modules), `GUIDES/` (user docs, generated), `REFERENCE/` (data models), `DESIGN/` (architecture), `OPERATIONS/` (infra/release), `INTEGRATIONS/` (n8n/tests) |
|
||||
|
||||
### P0b — UUID Naming
|
||||
|
||||
| # | Check | Rule |
|
||||
|---|-------|------|
|
||||
| 8 | `file_uuid` not bare `uuid` | All file references use `file_uuid` (see UUID Naming Rule above) |
|
||||
| 9 | `identity_uuid` not bare `uuid` | All identity references use `identity_uuid` |
|
||||
|
||||
### P1 — Suggested (3 items)
|
||||
|
||||
| # | Check | Note |
|
||||
|---|-------|------|
|
||||
| 1 | Cross-references | Link to related docs in API_WORKSPACE/, GUIDES/, REFERENCE/, DESIGN/, OPERATIONS/ |
|
||||
| 2 | Glossary terms | Define non-obvious terms inline or link glossary |
|
||||
| 3 | Diagrams | Include Mermaid/ASCII diagram for complex topics |
|
||||
|
||||
### Exception
|
||||
|
||||
`M4_workspace/` files are exempt from this checklist (free-format reply documents).
|
||||
|
||||
---
|
||||
|
||||
## Delivery Procedure
|
||||
|
||||
完整交付程序（M4_workspace → M5 → Release → Deploy → Public）見：
|
||||
|
||||
`docs_v1.0/OPERATIONS/DELIVERY_PROCEDURE.md`
|
||||
@@ -1,71 +0,0 @@
|
||||
# System Audit — 2026-05-17
|
||||
|
||||
## Current State
|
||||
|
||||
### Embedding Storage (三重冗余，無主)
|
||||
|
||||
| 資料類型 | PG pgvector | Qdrant | JSON 檔案 |
|
||||
|---------|------------|--------|-----------|
|
||||
| Sentence 向量 | `chunk.embedding` ✅ | `dev_v1` / `rule1_v2` / `sentence_*` ✅ | ❌ 無 |
|
||||
| Story 向量 | `chunk.embedding` ✅ | `dev_v1` / `dev_stories` ✅ | `.story_llm.json` ✅ |
|
||||
| Face 向量 | ❌ 已清除（依使用者指示） | `dev_faces` ✅ (97K) | `.face.json` ✅ |
|
||||
| Voice 向量 | ❌ 無 | `dev_voice` ✅ (4K) | ❌ 無 |
|
||||
|
||||
### Pipeline 問題
|
||||
|
||||
| 問題 | 影響 |
|
||||
|------|------|
|
||||
| `processor_results.duration_secs` 全為 0 | 無法查各步驟耗時 |
|
||||
| `processor_results.started_at/completed_at` 全 NULL | 時間線遺失 |
|
||||
| Redis timing 在 job 完成後被清掉 | 唯一 timing 來源消失 |
|
||||
| `get_chunk_by_chunk_id_and_uuid` 原本是 stub（已修） | Smart search 找不到 PG chunk |
|
||||
| `server.rs::search()` 未 mount 但仍編譯 | Dead code，混淆 Qdrant 用途 |
|
||||
| Face embedding 只寫 Qdrant 不寫 PG | 已刪除則全失 |
|
||||
|
||||
### Qdrant Collections 現況
|
||||
|
||||
| Collection | Points | 來源 | UUID |
|
||||
|-----------|--------|------|------|
|
||||
| `dev_v1` | 9,936 | PG rebuild | ✅ bd80fec... |
|
||||
| `dev_faces` | 97,000 | face.json rebuild | ✅ bd80fec... |
|
||||
| `dev_stories` | 560 | Snapshot | ✅ bd80fec... |
|
||||
| `dev_voice` | 4,188 | Snapshot | ✅ bd80fec... |
|
||||
| `dev_rule1_v2` | 3,417 | Snapshot | ✅ bd80fec... |
|
||||
| `sentence_story` | 4,188 | Snapshot | ✅ bd80fec... |
|
||||
| `sentence_summary` | 4,188 | Snapshot | ✅ bd80fec... |
|
||||
|
||||
## Safeguards & Fixes
|
||||
|
||||
### P0 — 必須修
|
||||
|
||||
| # | Fix | 做法 |
|
||||
|---|-----|------|
|
||||
| 1 | **Pipeline timing 寫入 DB** | `update_processor_result()` 加入 `started_at`、`completed_at`、`duration_secs` |
|
||||
| 2 | **Qdrant 不當主要儲存** | Embedding 以 PG `chunk.embedding` 為 source of truth，Qdrant 唯讀 cache |
|
||||
| 3 | **Smart search 只走 PG pgvector** | `search_parent_chunks_semantic` 已正確，無需 Qdrant |
|
||||
| 4 | **移除 `server.rs::search()` dead code** | 或 mount 到正式 route 並確認可用 |
|
||||
|
||||
### P1 — 建議修
|
||||
|
||||
| # | Fix | 做法 |
|
||||
|---|-----|------|
|
||||
| 5 | **刪除 Qdrant 前先 snapshot** | 自動 snapshot script |
|
||||
| 6 | **清理多餘 Qdrant collections** | `dev_voice` / `dev_stories` / `dev_rule1_v2` / `sentence_*` 無 server reader，可移除 |
|
||||
| 7 | **Face embedding 寫入 PG 或移除 dead code** | 目前 face Qdrant write 無人讀取，可移除 `sync_face_embeddings` |
|
||||
| 8 | **UUID 一致性檢查** | 同一 content 不應產生不同 UUID |
|
||||
|
||||
### P2 — 可選
|
||||
|
||||
| # | Fix | 做法 |
|
||||
|---|-----|------|
|
||||
| 9 | `chunk_selector.rs` （player binary）hardcode `momentry_rule1` | 改讀 env var 或 PG |
|
||||
| 10 | AGENTS.md 已加入 delete 安全規則 | ✅ Done |
|
||||
|
||||
## Data Recovery Path
|
||||
|
||||
| 資料來源 | 可恢復到 | 方法 |
|
||||
|---------|---------|------|
|
||||
| `chunk.embedding` (PG) | Qdrant `dev_v1` | SQL → Qdrant upsert |
|
||||
| `face.json` (磁碟) | Qdrant `dev_faces` | Python script |
|
||||
| `story_llm.json` (磁碟) | Qdrant `dev_stories` | Python script |
|
||||
| Qdrant snapshots (phase1) | Qdrant collections | Snapshot upload API |
|
||||
@@ -1,388 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>01 Auth - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: auth -->
|
||||
<!-- description: Authentication — login, logout, JWT, session cookie, API key -->
|
||||
<!-- depends: -->
|
||||
|
||||
<h2>Base URL</h2>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Environment</th>
|
||||
<th>URL</th>
|
||||
<th>Purpose</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Production</td>
|
||||
<td><code>http://localhost:3002</code></td>
|
||||
<td>Production deployment</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>External (M5)</td>
|
||||
<td><code>https://m5api.momentry.ddns.net</code></td>
|
||||
<td>Remote access</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h2>Variables</h2>
|
||||
<p>All examples in this documentation use these environment variables:</p>
|
||||
<div class="codehilite"><pre><span></span><code><span class="nv">API</span><span class="o">=</span><span class="s2">"http://localhost:3002"</span>
|
||||
<span class="nv">KEY</span><span class="o">=</span><span class="s2">"your-api-key-here"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h2>Authentication</h2>
|
||||
<p>All endpoints under <code>/api/v1/*</code> require authentication.
|
||||
The following endpoints are public (no auth needed):</p>
|
||||
<ul>
|
||||
<li><code>GET /health</code></li>
|
||||
<li><code>POST /api/v1/auth/login</code></li>
|
||||
<li><code>POST /api/v1/auth/logout</code></li>
|
||||
</ul>
|
||||
<h3>Three Authentication Modes</h3>
|
||||
<p>The system supports three authentication methods, checked in <strong>priority order</strong> by the middleware:</p>
|
||||
<div class="codehilite"><pre><span></span><code>Middleware priority:
|
||||
1. Session Cookie (Portal/browser)
|
||||
2. JWT Bearer (API clients, CLI)
|
||||
3. API Key Header (legacy compatibility)
|
||||
4. API Key Query Param (?api_key=)
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Mode</th>
|
||||
<th>Transport</th>
|
||||
<th>Expiry</th>
|
||||
<th>Scope</th>
|
||||
<th>Best for</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><strong>Session Cookie</strong></td>
|
||||
<td><code>Cookie: session_id=<session_id></code></td>
|
||||
<td>24h</td>
|
||||
<td>per-browser session</td>
|
||||
<td>Portal (browser)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>JWT</strong></td>
|
||||
<td><code>Authorization: Bearer <token></code></td>
|
||||
<td>1h</td>
|
||||
<td>per-login token</td>
|
||||
<td>API clients, CLI, scripts</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>API Key</strong></td>
|
||||
<td><code>X-API-Key: <key></code></td>
|
||||
<td>90d</td>
|
||||
<td>fixed key for automation</td>
|
||||
<td>Legacy scripts, WordPress</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3>Login</h3>
|
||||
<p><strong>Default accounts & API keys:</strong></p>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Username</th>
|
||||
<th>Password</th>
|
||||
<th>API Key</th>
|
||||
<th>Role</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>admin</code></td>
|
||||
<td><code>admin</code></td>
|
||||
<td>—</td>
|
||||
<td>admin</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>demo</code></td>
|
||||
<td><code>demo</code></td>
|
||||
<td><code>muser_demo_key_32chars_abcdef1234567890</code></td>
|
||||
<td>user</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The demo API key is set via <code>MOMENTRY_DEMO_API_KEY</code> env var and can be used in place of JWT for marcom integrations:</p>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Using API key instead of JWT</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/scan"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: muser_demo_key_32chars_abcdef1234567890"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Login as admin</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/auth/login"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"username": "admin", "password": "admin"}'</span>
|
||||
|
||||
<span class="c1"># Login as demo user</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/auth/login"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"username": "demo", "password": "demo"}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Success Response</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"jwt"</span><span class="p">:</span><span class="w"> </span><span class="s2">"eyJhbGciOiJIUzI1NiIs..."</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"api_key"</span><span class="p">:</span><span class="w"> </span><span class="s2">"muser_..."</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"user"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"username"</span><span class="p">:</span><span class="w"> </span><span class="s2">"admin"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"role"</span><span class="p">:</span><span class="w"> </span><span class="s2">"admin"</span>
|
||||
<span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="nt">"expires_at"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-05-18T13:00:00Z"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>jwt</code></td>
|
||||
<td>string</td>
|
||||
<td>JWT access token. Use as <code>Authorization: Bearer <jwt></code>. Expires in 1 hour.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>api_key</code></td>
|
||||
<td>string</td>
|
||||
<td>Legacy API key. Use as <code>X-API-Key: <key></code>. Good for 90 days.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>user.username</code></td>
|
||||
<td>string</td>
|
||||
<td>Username</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>user.role</code></td>
|
||||
<td>string</td>
|
||||
<td>Role: <code>admin</code>, <code>user</code>, or <code>readonly</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>expires_at</code></td>
|
||||
<td>string</td>
|
||||
<td>ISO8601 timestamp of JWT expiration</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The login endpoint also sets a <code>Set-Cookie</code> header for browser-based clients:</p>
|
||||
<div class="codehilite"><pre><span></span><code><span class="nt">Set-Cookie</span><span class="o">:</span><span class="w"> </span><span class="nt">session_id</span><span class="o">=<</span><span class="nt">session_id</span><span class="o">>;</span><span class="w"> </span><span class="nt">Path</span><span class="o">=/;</span><span class="w"> </span><span class="nt">HttpOnly</span><span class="o">;</span><span class="w"> </span><span class="nt">SameSite</span><span class="o">=</span><span class="nt">Strict</span><span class="o">;</span><span class="w"> </span><span class="nt">Max-Age</span><span class="o">=</span><span class="nt">86400</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Error Response (401)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Invalid username or password"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<hr />
|
||||
<h3>Using JWT</h3>
|
||||
<p>JWT is preferred for API clients (CLI scripts, WordPress). It is validated by the middleware without a database lookup (stateless).</p>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Login and capture JWT</span>
|
||||
<span class="nv">JWT</span><span class="o">=</span><span class="k">$(</span>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/auth/login"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"username":"admin","password":"admin"}'</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>python3<span class="w"> </span>-c<span class="w"> </span><span class="s2">"import json,sys;print(json.load(sys.stdin)['jwt'])"</span><span class="k">)</span>
|
||||
|
||||
<span class="c1"># Use JWT for all subsequent requests</span>
|
||||
curl<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/scan"</span>
|
||||
curl<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/resource/tmdb"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<p>JWT is short-lived (1 hour). When it expires, request a new one via login.</p>
|
||||
<hr />
|
||||
<h3>Using Session Cookie (Browser)</h3>
|
||||
<p>Browser-based clients (Portal) get a session cookie automatically after login. The browser sends the cookie with every request—no manual header needed.</p>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Login captures the session cookie from Set-Cookie header</span>
|
||||
curl<span class="w"> </span>-v<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/auth/login"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"username":"admin","password":"admin"}'</span><span class="w"> </span><span class="m">2</span>><span class="p">&</span><span class="m">1</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>grep<span class="w"> </span><span class="s2">"Set-Cookie"</span>
|
||||
|
||||
<span class="c1"># Browser automatically sends: Cookie: session_id=<session_id></span>
|
||||
<span class="c1"># No manual header needed for subsequent requests</span>
|
||||
</code></pre></div>
|
||||
|
||||
<p>The session cookie is HttpOnly (not accessible from JavaScript) and SameSite=Strict (protected against CSRF).</p>
|
||||
<hr />
|
||||
<h3>Using Legacy API Key</h3>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/scan"</span>
|
||||
|
||||
<span class="c1"># Also accepted via Bearer header (non-JWT format) or query parameter:</span>
|
||||
curl<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/scan"</span>
|
||||
curl<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/scan?api_key=</span><span class="nv">$KEY</span><span class="s2">"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<p>API keys are validated via SHA256 hash lookup in the database. They are long-lived (90 days) and intended for automation.</p>
|
||||
<h3>Obtaining an API Key (CLI)</h3>
|
||||
<div class="codehilite"><pre><span></span><code>momentry<span class="w"> </span>api-key<span class="w"> </span>create<span class="w"> </span><span class="s2">"My API Key"</span><span class="w"> </span>--key-type<span class="w"> </span>user
|
||||
</code></pre></div>
|
||||
|
||||
<hr />
|
||||
<h3>Logout</h3>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Logout using the session cookie (browser)</span>
|
||||
curl<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/auth/logout"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Cookie: session_id=<uuid>"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>What logout does</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Auth mode</th>
|
||||
<th>Effect</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><strong>Session Cookie</strong></td>
|
||||
<td>Session deleted from database. Same cookie returns 401 on subsequent requests.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>JWT</strong></td>
|
||||
<td>JWT remains valid until expiry. (JWT is stateless — logout adds JWT to a blacklist only if API key mode is used.)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>API Key</strong></td>
|
||||
<td>API key remains valid. (Legacy keys are shared across sessions — revoking would break other clients.)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example: full session lifecycle</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># 1. Login</span>
|
||||
<span class="nv">SESSION_ID</span><span class="o">=</span><span class="k">$(</span>curl<span class="w"> </span>-s<span class="w"> </span>-D<span class="w"> </span>-<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/auth/login"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"username":"admin","password":"admin"}'</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>grep<span class="w"> </span><span class="s2">"Set-Cookie"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>sed<span class="w"> </span><span class="s1">'s/.*session_id=\([^;]*\).*/\1/'</span><span class="k">)</span>
|
||||
|
||||
<span class="c1"># 2. Use session (works)</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-o<span class="w"> </span>/dev/null<span class="w"> </span>-w<span class="w"> </span><span class="s2">"HTTP %{http_code}\n"</span><span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/resource/tmdb"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Cookie: session_id=</span><span class="nv">$SESSION_ID</span><span class="s2">"</span>
|
||||
<span class="c1"># → HTTP 200</span>
|
||||
|
||||
<span class="c1"># 3. Logout</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/auth/logout"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Cookie: session_id=</span><span class="nv">$SESSION_ID</span><span class="s2">"</span>
|
||||
<span class="c1"># → {"success": true}</span>
|
||||
|
||||
<span class="c1"># 4. Use session again (rejected)</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-o<span class="w"> </span>/dev/null<span class="w"> </span>-w<span class="w"> </span><span class="s2">"HTTP %{http_code}\n"</span><span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/resource/tmdb"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Cookie: session_id=</span><span class="nv">$SESSION_ID</span><span class="s2">"</span>
|
||||
<span class="c1"># → HTTP 401</span>
|
||||
</code></pre></div>
|
||||
|
||||
<hr />
|
||||
<h3>Authentication Flow Summary</h3>
|
||||
<div class="codehilite"><pre><span></span><code>Login Request
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ 1. Check users │ ← users table (argon2 password verify)
|
||||
│ table │
|
||||
└──────┬───────────┘
|
||||
│
|
||||
┌───┴───┐
|
||||
│ match │
|
||||
└───┬───┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ 2. Create JWT │ ← 1h expiry, signed with JWT_SECRET
|
||||
├──────────────────┤
|
||||
│ 3. Create │ ← 24h expiry, stored in sessions table
|
||||
│ session │
|
||||
├──────────────────┤
|
||||
│ 4. Set-Cookie │ ← HttpOnly, SameSite=Strict, Path=/
|
||||
├──────────────────┤
|
||||
│ 5. Return │ ← JWT + api_key + user info to client
|
||||
└──────────────────┘
|
||||
</code></pre></div>
|
||||
|
||||
<div class="codehilite"><pre><span></span><code>Protected Request
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Middleware checks: │
|
||||
│ │
|
||||
│ 1. Cookie session? │ → DB lookup session → get api_key → verify
|
||||
│ │
|
||||
│ 2. JWT Bearer? │ → verify JWT signature → decode claims
|
||||
│ │
|
||||
│ 3. X-API-Key? │ → SHA256 hash → DB lookup → verify
|
||||
│ │
|
||||
│ 4. ?api_key=? │ → same as #3
|
||||
│ │
|
||||
│ 5. None → 401 │
|
||||
└──────────────────────┘
|
||||
</code></pre></div>
|
||||
|
||||
<hr />
|
||||
<h3>Error Responses</h3>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>HTTP</th>
|
||||
<th>When</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>401</code></td>
|
||||
<td>Missing or invalid authentication</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>401</code></td>
|
||||
<td>Session expired or logged out</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>401</code></td>
|
||||
<td>JWT expired</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>401</code></td>
|
||||
<td>API key revoked or inactive</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3>Related</h3>
|
||||
<ul>
|
||||
<li><code>POST /api/v1/resource/tmdb/check</code> — test authentication + TMDb API connectivity</li>
|
||||
<li><code>GET /health/detailed</code> — view auth status (integrations section)</li>
|
||||
</ul>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,277 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>02 Health - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: health -->
|
||||
<!-- description: Health check endpoints -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
<h2>Health Check</h2>
|
||||
<h3><code>GET /health</code></h3>
|
||||
<p><strong>Auth</strong>: Public
|
||||
<strong>Scope</strong>: system-level</p>
|
||||
<p>Returns basic server health status — used by load balancers and monitoring.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/health"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{status, version}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"version"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1.0.0"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"build_git_hash"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3a6c1865"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"build_timestamp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-05-16T13:38:15Z"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"uptime_ms"</span><span class="p">:</span><span class="w"> </span><span class="mi">3015</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>status</code></td>
|
||||
<td>string</td>
|
||||
<td><code>ok</code> or <code>degraded</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>version</code></td>
|
||||
<td>string</td>
|
||||
<td>Semver version</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>build_git_hash</code></td>
|
||||
<td>string</td>
|
||||
<td>Git commit hash</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>build_timestamp</code></td>
|
||||
<td>string</td>
|
||||
<td>Binary build time</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>uptime_ms</code></td>
|
||||
<td>integer</td>
|
||||
<td>Milliseconds since server start</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3><code>GET /health/detailed</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: system-level</p>
|
||||
<p>Returns full system health including each service status, resource utilization, pipeline readiness, schema migration status, identity file sync status, and external integrations.</p>
|
||||
<blockquote>
|
||||
<p>Requires authentication (JWT, session cookie, or API key). The basic <code>/health</code> endpoint remains public for load balancer checks.</p>
|
||||
</blockquote>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/health/detailed"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{status, services, resources: {cpu: .resources.cpu_used_percent, memory: .resources.memory_used_percent}}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"version"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1.0.0"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"services"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"postgres"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span><span class="w"> </span><span class="nt">"latency_ms"</span><span class="p">:</span><span class="w"> </span><span class="mi">3</span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="nt">"redis"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span><span class="w"> </span><span class="nt">"latency_ms"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="nt">"qdrant"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span><span class="w"> </span><span class="nt">"latency_ms"</span><span class="p">:</span><span class="w"> </span><span class="mi">5</span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="nt">"resources"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"cpu_used_percent"</span><span class="p">:</span><span class="w"> </span><span class="mf">12.5</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"memory_available_mb"</span><span class="p">:</span><span class="w"> </span><span class="mi">32768</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"memory_used_percent"</span><span class="p">:</span><span class="w"> </span><span class="mf">31.7</span>
|
||||
<span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="nt">"pipeline"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"scripts_ready"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"scripts_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">345</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"processors"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"asr"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"yolo"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"face"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"pose"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"ocr"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"cut"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"scene"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"asrx"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"visual_chunk"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||||
<span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="nt">"models_ready"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"models_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">42</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"scripts_integrity"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="nt">"matched"</span><span class="p">:</span><span class="w"> </span><span class="mi">332</span><span class="p">,</span><span class="w"> </span><span class="nt">"total"</span><span class="p">:</span><span class="w"> </span><span class="mi">345</span><span class="p">,</span><span class="w"> </span><span class="nt">"ok"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="nt">"ffmpeg"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||||
<span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="nt">"schema"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"table_exists"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"applied"</span><span class="p">:</span><span class="w"> </span><span class="p">[{</span><span class="nt">"filename"</span><span class="p">:</span><span class="w"> </span><span class="s2">"migrate_add_users_table.sql"</span><span class="p">}],</span>
|
||||
<span class="w"> </span><span class="nt">"required"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span>
|
||||
<span class="w"> </span><span class="nt">"ok"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||||
<span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="nt">"identities"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"directory_exists"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"files_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">3481</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"index_ok"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"db_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">3481</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"synced"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||||
<span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="nt">"integrations"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"tmdb"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"api_key_configured"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"enabled"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"api_reachable"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response Fields</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>status</code></td>
|
||||
<td>string</td>
|
||||
<td><code>ok</code> if all essential services healthy</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>services</code></td>
|
||||
<td>object</td>
|
||||
<td>Per-service status (postgres, redis, qdrant)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>services.*.status</code></td>
|
||||
<td>string</td>
|
||||
<td><code>ok</code>, <code>error</code>, or <code>degraded</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>services.*.latency_ms</code></td>
|
||||
<td>int</td>
|
||||
<td>Response time in milliseconds</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>resources</code></td>
|
||||
<td>object</td>
|
||||
<td>CPU, memory usage</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>pipeline.scripts_ready</code></td>
|
||||
<td>boolean</td>
|
||||
<td>Scripts directory accessible</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>pipeline.scripts_count</code></td>
|
||||
<td>int</td>
|
||||
<td>Number of Python processor scripts</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>pipeline.processors</code></td>
|
||||
<td>object</td>
|
||||
<td>Per-processor availability</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>pipeline.models_ready</code></td>
|
||||
<td>boolean</td>
|
||||
<td>Models directory accessible</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>pipeline.scripts_integrity</code></td>
|
||||
<td>object</td>
|
||||
<td>SHA256 checksum verification results</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>schema.ok</code></td>
|
||||
<td>boolean</td>
|
||||
<td>All required migrations applied</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>identities.synced</code></td>
|
||||
<td>boolean</td>
|
||||
<td>Identity file count matches DB count</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>integrations.tmdb</code></td>
|
||||
<td>object</td>
|
||||
<td>TMDB API key config and reachability</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Health status rules</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Condition</th>
|
||||
<th>status</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>All services ok</td>
|
||||
<td><code>ok</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Any service error</td>
|
||||
<td><code>degraded</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Postgres or Redis error</td>
|
||||
<td><code>degraded</code> (server still responds)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3>Stats Endpoints</h3>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Method</th>
|
||||
<th>Endpoint</th>
|
||||
<th>Auth</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>GET</td>
|
||||
<td><code>/api/v1/stats/sftpgo</code></td>
|
||||
<td>No</td>
|
||||
<td>SFTPGo service status</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,444 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>03 Register - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: register -->
|
||||
<!-- description: File registration — register, scan -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
<h2>File Registration</h2>
|
||||
<h3><code>POST /api/v1/files/register</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Register a video file for processing. Returns the file's metadata and UUID.</p>
|
||||
<p><strong>New in v0.1.2</strong>: Registration now <strong>automatically triggers the processing pipeline</strong> — no need to call <code>POST /api/v1/file/:file_uuid/process</code> separately. The system will:
|
||||
1. Register the file and run ffprobe
|
||||
2. Auto-run offline TMDb probe (reads local identity files, no API calls)
|
||||
3. Create a monitor job for the worker
|
||||
4. Worker starts all 10 processors (Cut → ASR → ASRX → YOLO → OCR → Face → Pose → VisualChunk → Story → 5W1H)</p>
|
||||
<p>If the file already exists (same content hash), returns the existing record with <code>already_exists: true</code>.</p>
|
||||
<h4>Request Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Default</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_path</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
<td>—</td>
|
||||
<td>Path to video file on disk</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>pattern</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td>—</td>
|
||||
<td>Regex pattern for batch register (requires <code>file_path</code> to be a directory)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>user_id</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>—</td>
|
||||
<td>User ID to associate with registration</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>content_hash</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td>—</td>
|
||||
<td>Pre-computed SHA-256 hash (skips computation)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Register a single file</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/register"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_path": "/path/to/video.mp4"}'</span>
|
||||
|
||||
<span class="c1"># Batch register files matching a pattern in a directory</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/register"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_path": "/path/to/dir", "pattern": ".*\\.mp4$"}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3a6c1865..."</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"video.mp4"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_path"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/path/to/video.mp4"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"video"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"duration"</span><span class="p">:</span><span class="w"> </span><span class="mf">120.5</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"width"</span><span class="p">:</span><span class="w"> </span><span class="mi">1920</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"height"</span><span class="p">:</span><span class="w"> </span><span class="mi">1080</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"fps"</span><span class="p">:</span><span class="w"> </span><span class="mf">24.0</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"total_frames"</span><span class="p">:</span><span class="w"> </span><span class="mi">2892</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"already_exists"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"File registered successfully"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>success</code></td>
|
||||
<td>boolean</td>
|
||||
<td>Always true on 200</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>32-char hex UUID of the registered file</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_name</code></td>
|
||||
<td>string</td>
|
||||
<td>File name (auto-renamed if name conflict)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_path</code></td>
|
||||
<td>string</td>
|
||||
<td>Canonical path on disk</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_type</code></td>
|
||||
<td>string</td>
|
||||
<td><code>"video"</code>, <code>"audio"</code>, or <code>"unknown"</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>duration</code></td>
|
||||
<td>float</td>
|
||||
<td>Duration in seconds</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>width</code></td>
|
||||
<td>integer</td>
|
||||
<td>Video width in pixels</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>height</code></td>
|
||||
<td>integer</td>
|
||||
<td>Video height in pixels</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>fps</code></td>
|
||||
<td>float</td>
|
||||
<td>Frames per second</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>total_frames</code></td>
|
||||
<td>integer</td>
|
||||
<td>Total frame count</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>already_exists</code></td>
|
||||
<td>boolean</td>
|
||||
<td>True if same content was already registered</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>message</code></td>
|
||||
<td>string</td>
|
||||
<td>Human-readable status</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Error Responses</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>HTTP</th>
|
||||
<th>When</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>401</code></td>
|
||||
<td>Missing or invalid API key</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>400</code></td>
|
||||
<td>Invalid request body</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>404</code></td>
|
||||
<td>File path does not exist</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/files/scan</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Scan the filesystem directory and list all media files, showing which are registered, processing, or unregistered.</p>
|
||||
<h4>Query Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Default</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>page</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>1</td>
|
||||
<td>Page number (1-based)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>page_size</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>all</td>
|
||||
<td>Items per page (alias: <code>limit</code>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>limit</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>all</td>
|
||||
<td>Max items (alias for <code>page_size</code>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>pattern</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td>—</td>
|
||||
<td>Regex filter on file name (e.g., <code>.*\\.mp4$</code>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>sort_by</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td><code>name</code></td>
|
||||
<td>Sort field: <code>name</code>, <code>size</code>, <code>modified</code>, <code>status</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>sort_order</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td><code>asc</code></td>
|
||||
<td>Sort direction: <code>asc</code> or <code>desc</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Full scan</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/scan"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{total, registered_count, unregistered_count}'</span>
|
||||
|
||||
<span class="c1"># Paginated (page 1, 5 per page)</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/scan?page=1&page_size=5"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{page, total_pages, files: [.files[].file_name]}'</span>
|
||||
|
||||
<span class="c1"># Regex filter: only mp4 files</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/scan?pattern=.*\\.mp4</span>$<span class="s2">"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{filtered_total, files: [.files[].file_name]}'</span>
|
||||
|
||||
<span class="c1"># Sort by file size (largest first)</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/scan?sort_by=size&sort_order=desc&page_size=5"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'[.files[] | {file_name, file_size}]'</span>
|
||||
|
||||
<span class="c1"># Sort by modified time (most recent first)</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/scan?sort_by=modified&sort_order=desc&page_size=5"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'[.files[] | {file_name, modified_time}]'</span>
|
||||
|
||||
<span class="c1"># Sort by status</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/scan?sort_by=status&page_size=5"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'[.files[] | {file_name, status}]'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"files"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"file_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"video.mp4"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_size"</span><span class="p">:</span><span class="w"> </span><span class="mi">12345678</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"is_registered"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3a6c1865..."</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"completed"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"registration_time"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-05-16T12:00:00Z"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"job_id"</span><span class="p">:</span><span class="w"> </span><span class="mi">42</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">],</span>
|
||||
<span class="w"> </span><span class="nt">"total"</span><span class="p">:</span><span class="w"> </span><span class="mi">107</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"filtered_total"</span><span class="p">:</span><span class="w"> </span><span class="mi">80</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"page"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"page_size"</span><span class="p">:</span><span class="w"> </span><span class="mi">20</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"total_pages"</span><span class="p">:</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"registered_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">26</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"unregistered_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">81</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>files</code></td>
|
||||
<td>array</td>
|
||||
<td>Array of file info objects (paginated)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>files[].file_name</code></td>
|
||||
<td>string</td>
|
||||
<td>File name</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>files[].relative_path</code></td>
|
||||
<td>string</td>
|
||||
<td>Path relative to scan root</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>files[].file_path</code></td>
|
||||
<td>string</td>
|
||||
<td>Absolute path on disk</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>files[].file_size</code></td>
|
||||
<td>integer</td>
|
||||
<td>File size in bytes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>files[].modified_time</code></td>
|
||||
<td>string</td>
|
||||
<td>Last modified timestamp (ISO8601)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>files[].is_registered</code></td>
|
||||
<td>boolean</td>
|
||||
<td>Whether file is registered in DB</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>files[].file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>32-char hex UUID (only if registered)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>files[].status</code></td>
|
||||
<td>string</td>
|
||||
<td><code>"completed"</code>, <code>"processing"</code>, <code>"registered"</code>, <code>"unregistered"</code>, or <code>null</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>files[].registration_time</code></td>
|
||||
<td>string</td>
|
||||
<td>DB registration timestamp (only if registered)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>files[].job_id</code></td>
|
||||
<td>integer</td>
|
||||
<td>Processing job ID (only if a job exists)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>total</code></td>
|
||||
<td>integer</td>
|
||||
<td>Total files found on disk (unfiltered)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>filtered_total</code></td>
|
||||
<td>integer</td>
|
||||
<td>Files matching regex filter</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>page</code></td>
|
||||
<td>integer</td>
|
||||
<td>Current page number</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>page_size</code></td>
|
||||
<td>integer</td>
|
||||
<td>Items per page</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>total_pages</code></td>
|
||||
<td>integer</td>
|
||||
<td>Total pages</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>registered_count</code></td>
|
||||
<td>integer</td>
|
||||
<td>Files registered in DB</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>unregistered_count</code></td>
|
||||
<td>integer</td>
|
||||
<td>Files not yet registered</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Notes</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Feature</th>
|
||||
<th>Behavior</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><strong>Regex</strong></td>
|
||||
<td>Case-insensitive (<code>(?i)</code> prefix auto-applied). Applied to <code>file_name</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Sort order</strong></td>
|
||||
<td>Default (<code>sort_by=name</code>): registered files first, then alphabetically. <code>sort_by=status</code>: alphabetical by status string.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Pagination</strong></td>
|
||||
<td><code>page_size</code> and <code>limit</code> are aliases. Default: show all results.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Processing order</strong></td>
|
||||
<td><code>pattern</code> regex filter → <code>sort_by</code>/<code>sort_order</code> → <code>page</code>/<code>page_size</code> slice.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,291 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>04 Lookup - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: lookup -->
|
||||
<!-- description: File lookup by name and unregistration -->
|
||||
<!-- depends: 01_auth, 03_register -->
|
||||
|
||||
<h2>File Lookup</h2>
|
||||
<h3><code>GET /api/v1/files/lookup</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Search registered files by file name. Performs a case-insensitive LIKE search on the file name column. Returns basic info about matching files.</p>
|
||||
<h4>Query Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_name</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
<td>File name to search for (partial matches supported)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Look up a specific file</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/lookup?file_name=video.mp4"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span>
|
||||
|
||||
<span class="c1"># Partial name search</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/files/lookup?file_name=charade"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'.matches[].file_name'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"file_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"video.mp4"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"exists"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"matches"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a03485a40b2df2d3"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"video.mp4"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"video"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"completed"</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">],</span>
|
||||
<span class="w"> </span><span class="nt">"next_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"video (2).mp4"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_name</code></td>
|
||||
<td>string</td>
|
||||
<td>Searched name</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>exists</code></td>
|
||||
<td>boolean</td>
|
||||
<td>Exact name match exists</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>matches</code></td>
|
||||
<td>array</td>
|
||||
<td>Array of matching registered files</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>matches[].file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>32-char hex UUID</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>matches[].file_name</code></td>
|
||||
<td>string</td>
|
||||
<td>Registered file name</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>matches[].file_type</code></td>
|
||||
<td>string</td>
|
||||
<td><code>"video"</code>, <code>"audio"</code>, or <code>null</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>matches[].status</code></td>
|
||||
<td>string</td>
|
||||
<td>Registration/processing status</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>next_name</code></td>
|
||||
<td>string</td>
|
||||
<td>Suggested name for avoiding conflicts</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h2>Unregister</h2>
|
||||
<h3><code>POST /api/v1/unregister</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Delete a registered file from the system. Supports single file by UUID, or batch by directory + regex pattern.</p>
|
||||
<h4>What gets deleted</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Removed (default)</th>
|
||||
<th>Not removed</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Database records (videos, chunks, embeddings, processor_results, pre_chunks)</td>
|
||||
<td>The original source video file on disk</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Processor output JSON files (<code>{uuid}.*.json</code>) — unless <code>delete_output_files: false</code></td>
|
||||
<td>Temp/working directories</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>In-memory cache entries</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MongoDB cached lists</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<blockquote>
|
||||
<p>⚠️ Database deletion is <strong>irreversible</strong>. To keep output files, set <code>"delete_output_files": false</code>.</p>
|
||||
</blockquote>
|
||||
<h4>Request Parameters</h4>
|
||||
<p>At least one mode must be specified: either <code>file_uuid</code> alone, or <code>file_path</code> + <code>pattern</code> together.</p>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Default</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>*</td>
|
||||
<td>—</td>
|
||||
<td>Single file UUID to delete</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_path</code></td>
|
||||
<td>string</td>
|
||||
<td>*</td>
|
||||
<td>—</td>
|
||||
<td>Directory path (for batch delete)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>pattern</code></td>
|
||||
<td>string</td>
|
||||
<td>*</td>
|
||||
<td>—</td>
|
||||
<td>Regex pattern (requires <code>file_path</code>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>delete_output_files</code></td>
|
||||
<td>boolean</td>
|
||||
<td>No</td>
|
||||
<td><code>true</code></td>
|
||||
<td>If <code>true</code>, also delete processor output JSON files (<code>{uuid}.*.json</code>). Set to <code>false</code> to keep them.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Delete a single file by UUID (default: also deletes output JSON files)</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/unregister"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_uuid": "'</span><span class="s2">"</span><span class="nv">$FILE_UUID</span><span class="s2">"</span><span class="s1">'"}'</span>
|
||||
|
||||
<span class="c1"># Keep output JSON files, only delete DB records</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/unregister"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_uuid": "'</span><span class="s2">"</span><span class="nv">$FILE_UUID</span><span class="s2">"</span><span class="s1">'", "delete_output_files": false}'</span>
|
||||
|
||||
<span class="c1"># Batch delete all mp4 files in a directory</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/unregister"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_path": "/path/to/dir", "pattern": ".*\\.mp4$"}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a03485a40b2df2d3"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Video unregistered successfully"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>success</code></td>
|
||||
<td>boolean</td>
|
||||
<td>True if deletion succeeded</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>UUID of the deleted file (single mode)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>message</code></td>
|
||||
<td>string</td>
|
||||
<td>Human-readable status</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Error Responses</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>HTTP</th>
|
||||
<th>When</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>400</code></td>
|
||||
<td>Neither <code>file_uuid</code> nor <code>file_path</code>+<code>pattern</code> provided</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>404</code></td>
|
||||
<td>File UUID not found</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>401</code></td>
|
||||
<td>Missing or invalid API key</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,505 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>05 Process - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: process -->
|
||||
<!-- description: Processing pipeline — trigger, probe, progress, jobs -->
|
||||
<!-- depends: 01_auth, 03_register -->
|
||||
|
||||
<h2>Processing Pipeline</h2>
|
||||
<h3><code>POST /api/v1/file/:file_uuid/process</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Trigger the processing pipeline for a registered file. Creates a monitor job that the worker picks up and processes sequentially. Returns immediately with the job info—processing runs asynchronously in the background.</p>
|
||||
<h4>Request Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Default</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>processors</code></td>
|
||||
<td>string[]</td>
|
||||
<td>No</td>
|
||||
<td>all</td>
|
||||
<td>Specific processors to run: <code>["cut","asr","asrx","yolo","ocr","face","pose","visual_chunk","story","5w1h"]</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>rules</code></td>
|
||||
<td>string[]</td>
|
||||
<td>No</td>
|
||||
<td>all</td>
|
||||
<td>Rule names to apply (currently unused)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Run all processors</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/file/</span><span class="nv">$FILE_UUID</span><span class="s2">/process"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span>-d<span class="w"> </span><span class="s1">'{}'</span>
|
||||
|
||||
<span class="c1"># Run specific processors only</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/file/</span><span class="nv">$FILE_UUID</span><span class="s2">/process"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"processors": ["asr", "face", "yolo"]}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"job_id"</span><span class="p">:</span><span class="w"> </span><span class="mi">42</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3a6c1865..."</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"processing"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"pids"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="mi">12345</span><span class="p">,</span><span class="w"> </span><span class="mi">12346</span><span class="p">],</span>
|
||||
<span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Processing triggered for video.mp4"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>success</code></td>
|
||||
<td>boolean</td>
|
||||
<td>Always true on 200</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>job_id</code></td>
|
||||
<td>integer</td>
|
||||
<td>Monitor job ID (for job tracking)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>32-char hex UUID of the file</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>status</code></td>
|
||||
<td>string</td>
|
||||
<td><code>"processing"</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>pids</code></td>
|
||||
<td>integer[]</td>
|
||||
<td>Process IDs of started processors</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>message</code></td>
|
||||
<td>string</td>
|
||||
<td>Human-readable status</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Error Responses</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>HTTP</th>
|
||||
<th>When</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>404</code></td>
|
||||
<td>File UUID not found</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>401</code></td>
|
||||
<td>Missing or invalid API key</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/file/:file_uuid/probe</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Get ffprobe metadata for a registered file. Returns video/audio stream info, codec details, duration, resolution, and frame rate.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/file/</span><span class="nv">$FILE_UUID</span><span class="s2">/probe"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3a6c1865..."</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"video.mp4"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_size"</span><span class="p">:</span><span class="w"> </span><span class="mi">794863677</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"duration"</span><span class="p">:</span><span class="w"> </span><span class="mf">120.5</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"width"</span><span class="p">:</span><span class="w"> </span><span class="mi">1920</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"height"</span><span class="p">:</span><span class="w"> </span><span class="mi">1080</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"fps"</span><span class="p">:</span><span class="w"> </span><span class="mf">24.0</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"total_frames"</span><span class="p">:</span><span class="w"> </span><span class="mi">2892</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"cached"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"format"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"filename"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/path/to/video.mp4"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"format_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"mov,mp4,m4a,3gp"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"duration"</span><span class="p">:</span><span class="w"> </span><span class="s2">"120.5"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"size"</span><span class="p">:</span><span class="w"> </span><span class="s2">"12345678"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"bit_rate"</span><span class="p">:</span><span class="w"> </span><span class="s2">"819200"</span>
|
||||
<span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="nt">"streams"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"index"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"codec_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"h264"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"codec_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"video"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"width"</span><span class="p">:</span><span class="w"> </span><span class="mi">1920</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"height"</span><span class="p">:</span><span class="w"> </span><span class="mi">1080</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"r_frame_rate"</span><span class="p">:</span><span class="w"> </span><span class="s2">"24/1"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"duration"</span><span class="p">:</span><span class="w"> </span><span class="s2">"120.5"</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">]</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>32-char hex UUID</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_name</code></td>
|
||||
<td>string</td>
|
||||
<td>File name</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_size</code></td>
|
||||
<td>integer</td>
|
||||
<td>File size in bytes (from filesystem)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>duration</code></td>
|
||||
<td>float</td>
|
||||
<td>Duration in seconds</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>width</code></td>
|
||||
<td>integer</td>
|
||||
<td>Video width in pixels</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>height</code></td>
|
||||
<td>integer</td>
|
||||
<td>Video height in pixels</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>fps</code></td>
|
||||
<td>float</td>
|
||||
<td>Frames per second</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>total_frames</code></td>
|
||||
<td>integer</td>
|
||||
<td>Estimated total frames</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>cached</code></td>
|
||||
<td>boolean</td>
|
||||
<td>True if result was from cached probe JSON</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>format</code></td>
|
||||
<td>object</td>
|
||||
<td>Container format info (ffprobe format section)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>streams</code></td>
|
||||
<td>array</td>
|
||||
<td>Array of stream info objects</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/progress/:file_uuid</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Get real-time processing progress for a file via Redis pub/sub. Includes per-processor status, current/total frames, ETA, and system resource stats.</p>
|
||||
<h4>Pipeline Order</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Order</th>
|
||||
<th>Processor</th>
|
||||
<th>Dependencies</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>1</td>
|
||||
<td><code>cut</code></td>
|
||||
<td>—</td>
|
||||
<td>Scene detection</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>2</td>
|
||||
<td><code>asr</code></td>
|
||||
<td>cut</td>
|
||||
<td>Speech-to-text (per scene)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>3</td>
|
||||
<td><code>asrx</code></td>
|
||||
<td>asr</td>
|
||||
<td>Speaker diarization</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>4</td>
|
||||
<td><code>yolo</code></td>
|
||||
<td>—</td>
|
||||
<td>Object detection</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>5</td>
|
||||
<td><code>ocr</code></td>
|
||||
<td>—</td>
|
||||
<td>Text recognition</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>6</td>
|
||||
<td><code>face</code></td>
|
||||
<td>—</td>
|
||||
<td>Face detection & embedding</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>7</td>
|
||||
<td><code>pose</code></td>
|
||||
<td>—</td>
|
||||
<td>Pose estimation</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>8</td>
|
||||
<td><code>visual_chunk</code></td>
|
||||
<td>yolo</td>
|
||||
<td>Visual scene chunks</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>9</td>
|
||||
<td><code>story</code></td>
|
||||
<td>asr, asrx, cut, yolo, face</td>
|
||||
<td>Scene summaries (template)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>10</td>
|
||||
<td><code>5w1h</code></td>
|
||||
<td>story</td>
|
||||
<td>5W1H analysis (Gemma4 LLM)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>All processors except <code>story</code> and <code>5w1h</code> run concurrently when their dependencies are met. Story and 5W1H run sequentially after their prerequisites.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/progress/</span><span class="nv">$FILE_UUID</span><span class="s2">"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{overall_progress, processors: [.processors[] | {processor_type, status}]}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3a6c1865..."</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"overall_progress"</span><span class="p">:</span><span class="w"> </span><span class="mi">71</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"cpu_percent"</span><span class="p">:</span><span class="w"> </span><span class="mf">45.2</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"gpu_percent"</span><span class="p">:</span><span class="w"> </span><span class="mf">30.1</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"memory_percent"</span><span class="p">:</span><span class="w"> </span><span class="mf">62.4</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"processors"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="nt">"processor_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"asr"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"complete"</span><span class="p">,</span><span class="w"> </span><span class="nt">"progress"</span><span class="p">:</span><span class="w"> </span><span class="mi">100</span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="nt">"processor_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"yolo"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"running"</span><span class="p">,</span><span class="w"> </span><span class="nt">"progress"</span><span class="p">:</span><span class="w"> </span><span class="mi">65</span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="nt">"processor_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"face"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pending"</span><span class="p">,</span><span class="w"> </span><span class="nt">"progress"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">]</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>32-char hex UUID</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>overall_progress</code></td>
|
||||
<td>integer</td>
|
||||
<td>Overall progress percentage (0–100)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>processors</code></td>
|
||||
<td>array</td>
|
||||
<td>Per-processor status list</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>processors[].processor_type</code></td>
|
||||
<td>string</td>
|
||||
<td>Processor name (<code>asr</code>, <code>cut</code>, <code>yolo</code>, etc.)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>processors[].status</code></td>
|
||||
<td>string</td>
|
||||
<td><code>"pending"</code>, <code>"running"</code>, <code>"complete"</code>, or <code>"failed"</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>processors[].progress</code></td>
|
||||
<td>integer</td>
|
||||
<td>Per-processor progress (0–100)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>processors[].eta_seconds</code></td>
|
||||
<td>integer</td>
|
||||
<td>Estimated seconds remaining (running processors)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>processors[].current</code></td>
|
||||
<td>integer</td>
|
||||
<td>Current frame count</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>processors[].total</code></td>
|
||||
<td>integer</td>
|
||||
<td>Total frame count</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>cpu_percent</code></td>
|
||||
<td>float</td>
|
||||
<td>Current CPU usage</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>gpu_percent</code></td>
|
||||
<td>float</td>
|
||||
<td>Current GPU utilization</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>memory_percent</code></td>
|
||||
<td>float</td>
|
||||
<td>Current memory usage</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/jobs</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: system-level</p>
|
||||
<p>List all processing jobs (monitor jobs) in the system. Shows job status, which file each job is processing, and current processor info.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/jobs"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{count, jobs: [.jobs[] | {uuid, status}]}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"jobs"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">42</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3a6c1865..."</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"running"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"current_processor"</span><span class="p">:</span><span class="w"> </span><span class="s2">"yolo"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"created_at"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-05-16T12:00:00Z"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"started_at"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-05-16T12:01:00Z"</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">],</span>
|
||||
<span class="w"> </span><span class="nt">"count"</span><span class="p">:</span><span class="w"> </span><span class="mi">15</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"page"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"page_size"</span><span class="p">:</span><span class="w"> </span><span class="mi">20</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>jobs</code></td>
|
||||
<td>array</td>
|
||||
<td>Array of job info objects</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>jobs[].id</code></td>
|
||||
<td>integer</td>
|
||||
<td>Job ID</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>jobs[].uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>File UUID being processed</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>jobs[].status</code></td>
|
||||
<td>string</td>
|
||||
<td><code>"pending"</code>, <code>"running"</code>, <code>"completed"</code>, <code>"failed"</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>jobs[].current_processor</code></td>
|
||||
<td>string</td>
|
||||
<td>Currently active processor, or null</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>count</code></td>
|
||||
<td>integer</td>
|
||||
<td>Total job count</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>page</code></td>
|
||||
<td>integer</td>
|
||||
<td>Current page number</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>page_size</code></td>
|
||||
<td>integer</td>
|
||||
<td>Jobs per page</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,280 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>06 Search - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: search -->
|
||||
<!-- description: Vector search, BM25, smart search, universal search, visual search -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
<h2>Search APIs</h2>
|
||||
<h3><code>POST /api/v1/search/smart</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Semantic vector search using EmbeddingGemma-300m. Generates a query embedding via EmbeddingGemma (port 11436), then searches pgvector <code>story_parent</code> and <code>llm_parent</code> chunks by cosine similarity.</p>
|
||||
<h4>Request Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Default</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
<td>—</td>
|
||||
<td>File UUID to search within</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>query</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
<td>—</td>
|
||||
<td>Search text</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>limit</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>5</td>
|
||||
<td>Max results to return</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>page</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>1</td>
|
||||
<td>Page number</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>page_size</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>5</td>
|
||||
<td>Items per page</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/search/smart"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_uuid": "'</span><span class="s2">"</span><span class="nv">$FILE_UUID</span><span class="s2">"</span><span class="s1">'", "query": "Audrey Hepburn"}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"query"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Audrey Hepburn"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"results"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"parent_id"</span><span class="p">:</span><span class="w"> </span><span class="mi">1087822</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"scene_order"</span><span class="p">:</span><span class="w"> </span><span class="mi">1087822</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"start_frame"</span><span class="p">:</span><span class="w"> </span><span class="mi">104438</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"end_frame"</span><span class="p">:</span><span class="w"> </span><span class="mi">104538</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"fps"</span><span class="p">:</span><span class="w"> </span><span class="mf">24.0</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"start_time"</span><span class="p">:</span><span class="w"> </span><span class="mf">4351.6</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"end_time"</span><span class="p">:</span><span class="w"> </span><span class="mf">4355.76</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"summary"</span><span class="p">:</span><span class="w"> </span><span class="s2">"[4352s-4356s, 4s] Cast: Audrey Hepburn. Total: 2 lines, 10 words. Speakers: Audrey Hepburn (2 lines)"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"similarity"</span><span class="p">:</span><span class="w"> </span><span class="mf">0.67</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">],</span>
|
||||
<span class="w"> </span><span class="nt">"page"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"page_size"</span><span class="p">:</span><span class="w"> </span><span class="mi">5</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"strategy"</span><span class="p">:</span><span class="w"> </span><span class="s2">"semantic_vector_search"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<hr />
|
||||
<h3><code>POST /api/v1/search/universal</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Multi-type BM25 full-text search across chunks, frames, and persons. Uses PostgreSQL <code>tsvector</code>.</p>
|
||||
<h4>Request Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Default</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>query</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
<td>—</td>
|
||||
<td>Search text</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td>—</td>
|
||||
<td>Restrict to specific file</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>types</code></td>
|
||||
<td>string[]</td>
|
||||
<td>No</td>
|
||||
<td><code>["chunk","frame","person"]</code></td>
|
||||
<td>Search types</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>limit</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>10</td>
|
||||
<td>Max results per type</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>page</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>1</td>
|
||||
<td>Page number</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>page_size</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>20</td>
|
||||
<td>Items per page</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/search/universal"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_uuid": "'</span><span class="s2">"</span><span class="nv">$FILE_UUID</span><span class="s2">"</span><span class="s1">'", "query": "Cary Grant"}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"results"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"chunk"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"chunk_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"bd80fec92b0b6963d177a2c55bf713e2_2"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"chunk_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"story_child"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"start_frame"</span><span class="p">:</span><span class="w"> </span><span class="mi">5103</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"end_frame"</span><span class="p">:</span><span class="w"> </span><span class="mi">5127</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"start_time"</span><span class="p">:</span><span class="w"> </span><span class="mf">212.64</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"end_time"</span><span class="p">:</span><span class="w"> </span><span class="mf">213.64</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"text"</span><span class="p">:</span><span class="w"> </span><span class="s2">"[213s-214s] Cary Grant: \"Olá!\""</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"score"</span><span class="p">:</span><span class="w"> </span><span class="mf">0.9</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">],</span>
|
||||
<span class="w"> </span><span class="nt">"total"</span><span class="p">:</span><span class="w"> </span><span class="mi">20</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"took_ms"</span><span class="p">:</span><span class="w"> </span><span class="mi">18</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<hr />
|
||||
<h3><code>POST /api/v1/search/frames</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Search face detection frames by identity name or trace ID.</p>
|
||||
<hr />
|
||||
<h3><code>POST /api/v1/search/identity_text</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Search text chunks spoken by a specific identity.</p>
|
||||
<hr />
|
||||
<h3>Visual Search</h3>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Method</th>
|
||||
<th>Endpoint</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>POST</td>
|
||||
<td><code>/api/v1/search/visual</code></td>
|
||||
<td>Search visual chunks</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>POST</td>
|
||||
<td><code>/api/v1/search/visual/class</code></td>
|
||||
<td>Search by object class</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>POST</td>
|
||||
<td><code>/api/v1/search/visual/density</code></td>
|
||||
<td>Search by object density</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>POST</td>
|
||||
<td><code>/api/v1/search/visual/combination</code></td>
|
||||
<td>Search by object combination</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>POST</td>
|
||||
<td><code>/api/v1/search/visual/stats</code></td>
|
||||
<td>Visual chunk statistics</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Embedding Model</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Detail</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><strong>Model</strong></td>
|
||||
<td>EmbeddingGemma-300m</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Endpoint</strong></td>
|
||||
<td><code>POST /api/v1/embeddings</code> on port 11436</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Dimension</strong></td>
|
||||
<td>768</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Storage</strong></td>
|
||||
<td>pgvector (<code>chunk.embedding</code> column)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,510 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>07 Identity - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: identity -->
|
||||
<!-- description: Global identities — CRUD, detail, files, faces, bind, unbind, search -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
<h2>Global Identities</h2>
|
||||
<h3><code>GET /api/v1/identities</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>List all registered identities with pagination.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/identities?page=1&page_size=20"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{count, identities: [.identities[] | {name}]}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/identity/:identity_uuid</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>Get detailed information for a specific identity, including metadata and TMDb references.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/identity/</span><span class="nv">$IDENTITY_UUID</span><span class="s2">"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"identity_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a9a901056d6b46ff92da0c3c1a57dff4"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Cary Grant"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"identity_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"people"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"source"</span><span class="p">:</span><span class="w"> </span><span class="s2">"tmdb"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"confirmed"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"tmdb_id"</span><span class="p">:</span><span class="w"> </span><span class="mi">112</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"tmdb_profile"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{output}/identities/{identity_uuid}/profile.jpg"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"metadata"</span><span class="p">:</span><span class="w"> </span><span class="p">{},</span>
|
||||
<span class="w"> </span><span class="nt">"reference_data"</span><span class="p">:</span><span class="w"> </span><span class="p">{},</span>
|
||||
<span class="w"> </span><span class="nt">"created_at"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-05-16T12:00:00Z"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"updated_at"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>identity_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>Identity identifier</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>name</code></td>
|
||||
<td>string</td>
|
||||
<td>Identity name</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>identity_type</code></td>
|
||||
<td>string</td>
|
||||
<td><code>"people"</code> or null</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>source</code></td>
|
||||
<td>string</td>
|
||||
<td><code>.json</code>, <code>auto</code>, <code>tmdb</code>, <code>user_defined</code>, or <code>merged</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>status</code></td>
|
||||
<td>string</td>
|
||||
<td><code>"confirmed"</code>, <code>"pending"</code>, or <code>"inactive"</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>tmdb_id</code></td>
|
||||
<td>integer</td>
|
||||
<td>TMDb person ID (only if source = tmdb)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>tmdb_profile</code></td>
|
||||
<td>string</td>
|
||||
<td>Local profile image path (<code>{output}/identities/{uuid}/profile.jpg</code>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>metadata</code></td>
|
||||
<td>object</td>
|
||||
<td>Metadata JSON (tmdb_character, cast_order, etc.)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>created_at</code></td>
|
||||
<td>string</td>
|
||||
<td>Creation timestamp</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3><code>DELETE /api/v1/identity/:identity_uuid</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>Delete an identity permanently.</p>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/identity/:identity_uuid/files</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>Get all files where this identity appears. Returns per-file summary including face count, confidence, and appearance time range.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/identity/</span><span class="nv">$IDENTITY_UUID</span><span class="s2">/files"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/identity/:identity_uuid/faces</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>Get all face detection records associated with this identity.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/identity/</span><span class="nv">$IDENTITY_UUID</span><span class="s2">/faces"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>File where face was detected</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>frame_number</code></td>
|
||||
<td>integer</td>
|
||||
<td>Frame number of detection</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>face_id</code></td>
|
||||
<td>string</td>
|
||||
<td>Face ID (format: <code>face_{frame_number}</code>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>confidence</code></td>
|
||||
<td>float</td>
|
||||
<td>Detection confidence</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/identity/:identity_uuid/chunks</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>Get all text chunks (sentences) spoken while this identity's face was on screen. Useful for finding what a person said.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/identity/</span><span class="nv">$IDENTITY_UUID</span><span class="s2">/chunks"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"identity_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a9a901056d6b46ff92da0c3c1a57dff4"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"data"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"bd80fec92b0b6963d177a2c55bf713e2"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"chunk_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"bd80fec92b0b6963d177a2c55bf713e2_2"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"chunk_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sentence"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"start_frame"</span><span class="p">:</span><span class="w"> </span><span class="mi">5103</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"end_frame"</span><span class="p">:</span><span class="w"> </span><span class="mi">5127</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"fps"</span><span class="p">:</span><span class="w"> </span><span class="mf">24.0</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"start_time"</span><span class="p">:</span><span class="w"> </span><span class="mf">212.64</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"end_time"</span><span class="p">:</span><span class="w"> </span><span class="mf">213.64</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"text_content"</span><span class="p">:</span><span class="w"> </span><span class="s2">"[213s-214s] Cary Grant: \"Olá!\""</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">]</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>File identifier</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>chunk_id</code></td>
|
||||
<td>string</td>
|
||||
<td>Sentence chunk identifier</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>start_frame</code></td>
|
||||
<td>integer</td>
|
||||
<td>Frame-accurate start position</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>end_frame</code></td>
|
||||
<td>integer</td>
|
||||
<td>Frame-accurate end position</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>fps</code></td>
|
||||
<td>float</td>
|
||||
<td>Frames per second</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>start_time</code></td>
|
||||
<td>float</td>
|
||||
<td>Start time in seconds</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>end_time</code></td>
|
||||
<td>float</td>
|
||||
<td>End time in seconds</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>text_content</code></td>
|
||||
<td>string</td>
|
||||
<td>Spoken text content</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3><code>POST /api/v1/identity/:identity_uuid/bind</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>Bind a face detection to an identity. Associates the face trace with the identity for future search and recognition.</p>
|
||||
<h4>Request Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
<td>File where face is detected</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>face_id</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
<td>Face ID (format: <code>{frame}_{idx}</code>)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/identity/</span><span class="nv">$IDENTITY_UUID</span><span class="s2">/bind"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_uuid": "'</span><span class="s2">"</span><span class="nv">$FILE_UUID</span><span class="s2">"</span><span class="s1">'", "face_id": "1_5"}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<hr />
|
||||
<h3><code>POST /api/v1/identity/:identity_uuid/unbind</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>Unbind a face detection from an identity. Removes the identity association from the face record.</p>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/identities/search</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>Search identities by name (ILIKE search). Returns matching identity records.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/identities/search?q=Cary"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>name</code></td>
|
||||
<td>string</td>
|
||||
<td>Identity name</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>source</code></td>
|
||||
<td>string</td>
|
||||
<td>Identity source</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>tmdb_id</code></td>
|
||||
<td>integer</td>
|
||||
<td>TMDb ID (if source = tmdb)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>Associated file</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<hr />
|
||||
<h3><code>POST /api/v1/identity/upload</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>Upload an identity.json file to create or update an identity. Accepts the same format as the identity.json files stored on disk.</p>
|
||||
<p>If an identity with the same <code>name</code> already exists, it will be updated with the new values.</p>
|
||||
<h4>Request</h4>
|
||||
<p>The request body is an <code>IdentityFile</code> object:</p>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>identity_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
<td>Identity identifier</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>name</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
<td>Identity display name</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>identity_type</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td><code>"people"</code> or null</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>source</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td><code>.json</code>, <code>auto</code>, <code>tmdb</code>, <code>user_defined</code>, or <code>merged</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>status</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td><code>"confirmed"</code>, <code>"pending"</code>, or <code>"inactive"</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>tmdb_id</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>TMDb person ID</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>tmdb_profile</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td>TMDb profile image URL</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>metadata</code></td>
|
||||
<td>object</td>
|
||||
<td>No</td>
|
||||
<td>Arbitrary metadata JSON</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>file_bindings</code></td>
|
||||
<td>array</td>
|
||||
<td>No</td>
|
||||
<td>Array of <code>{ file_uuid, trace_ids, face_count }</code> (informational)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/identity/upload"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{</span>
|
||||
<span class="s1"> "version": 1,</span>
|
||||
<span class="s1"> "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",</span>
|
||||
<span class="s1"> "name": "Cary Grant",</span>
|
||||
<span class="s1"> "identity_type": "people",</span>
|
||||
<span class="s1"> "source": ".json",</span>
|
||||
<span class="s1"> "status": "confirmed",</span>
|
||||
<span class="s1"> "metadata": {},</span>
|
||||
<span class="s1"> "file_bindings": []</span>
|
||||
<span class="s1"> }'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"identity_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a9a901056d6b46ff92da0c3c1a57dff4"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Cary Grant"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Identity uploaded successfully"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<hr />
|
||||
<hr />
|
||||
<h3><code>POST /api/v1/identity/:identity_uuid/profile-image</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>Upload a profile image (JPEG or PNG) for an identity. The image is saved to <code>{output}/identities/{uuid}/profile.{ext}</code>.</p>
|
||||
<p>Uses <code>multipart/form-data</code> with field name <code>image</code>.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/identity/</span><span class="nv">$IDENTITY_UUID</span><span class="s2">/profile-image"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-F<span class="w"> </span><span class="s2">"image=@/path/to/photo.jpg"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"identity_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a9a901056d6b46ff92da0c3c1a57dff4"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"path"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/path/to/output/identities/.../profile.jpg"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Profile image saved: profile.jpg"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Error Responses</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>HTTP</th>
|
||||
<th>When</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>400</code></td>
|
||||
<td>Missing image field or unsupported format</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>404</code></td>
|
||||
<td>Identity not found</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>415</code></td>
|
||||
<td>Unsupported image type (use JPEG or PNG)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/identity/:identity_uuid/profile-image</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: identity-level</p>
|
||||
<p>Retrieve the profile image for an identity. Returns the raw image data with appropriate Content-Type header.</p>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/identity/</span><span class="nv">$IDENTITY_UUID</span><span class="s2">/profile-image"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span>-o<span class="w"> </span>profile.jpg
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Response Header</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>content-type</code></td>
|
||||
<td><code>image/jpeg</code> or <code>image/png</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,97 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>08 Identity Agent - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: identity_agent -->
|
||||
<!-- description: Identity agent — match from photo, match from trace -->
|
||||
<!-- depends: 01_auth, 07_identity -->
|
||||
|
||||
<h2>Identity Agent</h2>
|
||||
<h3><code>POST /api/v1/agents/identity/match-from-photo</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Upload a face photo to match against known identities. Detects face via InsightFace, extracts 512D embedding via CoreML FaceNet, then searches pgvector for the closest identity.</p>
|
||||
<h4>Request</h4>
|
||||
<p><code>multipart/form-data</code> with field <code>image</code> (JPEG/PNG) and optional <code>file_uuid</code>.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/agents/identity/match-from-photo"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-F<span class="w"> </span><span class="s2">"image=@/path/to/face.jpg"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-F<span class="w"> </span><span class="s2">"file_uuid=</span><span class="nv">$FILE_UUID</span><span class="s2">"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"matches"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"identity_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a9a90105..."</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Cary Grant"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"similarity"</span><span class="p">:</span><span class="w"> </span><span class="mf">0.87</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">]</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<hr />
|
||||
<h3><code>POST /api/v1/agents/identity/match-from-trace</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Match a face trace (tracked face across frames) against known identities. Samples 3 angles from the trace, generates embeddings, and searches pgvector.</p>
|
||||
<h4>Request Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
<td>File containing the trace</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>trace_id</code></td>
|
||||
<td>integer</td>
|
||||
<td>Yes</td>
|
||||
<td>Face trace ID to match</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/agents/identity/match-from-trace"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_uuid": "'</span><span class="s2">"</span><span class="nv">$FILE_UUID</span><span class="s2">"</span><span class="s1">'", "trace_id": 10}'</span>
|
||||
</code></pre></div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,303 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>08 Media - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: media -->
|
||||
<!-- description: Video streaming & frame extraction -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
<h2>Video Streaming & Frame Extraction</h2>
|
||||
<p>All video streaming endpoints support the following common query parameters:</p>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Default</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>mode</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td><code>normal</code></td>
|
||||
<td><code>normal</code> or <code>debug</code> (draws detection overlays)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>audio</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td><code>on</code></td>
|
||||
<td><code>on</code> or <code>off</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/file/:file_uuid/video</code></h3>
|
||||
<p>Stream the full video file with range support for seeking.</p>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<h4>Response</h4>
|
||||
<ul>
|
||||
<li><strong>200</strong>: Video stream (<code>Content-Type</code> based on file extension)</li>
|
||||
<li><strong>206</strong>: Partial content (range request)</li>
|
||||
<li>Supports <code>Range</code> header for seeking</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/file/:file_uuid/trace/:trace_id/video</code></h3>
|
||||
<p>Stream video with highlights for a specific face trace (follows a single person across frames with bounding box overlay).</p>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/file/:file_uuid/video/bbox</code></h3>
|
||||
<p>Stream video with bounding box overlay for all detected objects/faces.</p>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Uses a built-in 5×7 bitmap font renderer to draw labels directly on video frames via FFmpeg <code>drawtext</code> filter.</p>
|
||||
<hr />
|
||||
<h3><code>GET /api/v1/file/:file_uuid/thumbnail</code></h3>
|
||||
<p>Extract a single frame from a video as JPEG image. Uses FFmpeg <code>select</code> filter.</p>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<h4>Query Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Default</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>frame</code></td>
|
||||
<td>integer</td>
|
||||
<td>Yes</td>
|
||||
<td>—</td>
|
||||
<td>Zero-based frame number to extract</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>x</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>—</td>
|
||||
<td>Crop start X (left edge). Requires <code>y</code>, <code>w</code>, <code>h</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>y</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>—</td>
|
||||
<td>Crop start Y (top edge). Requires <code>x</code>, <code>w</code>, <code>h</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>w</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>—</td>
|
||||
<td>Crop width in pixels. Requires <code>x</code>, <code>y</code>, <code>h</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>h</code></td>
|
||||
<td>integer</td>
|
||||
<td>No</td>
|
||||
<td>—</td>
|
||||
<td>Crop height in pixels. Requires <code>x</code>, <code>y</code>, <code>w</code>.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>All four crop params (<code>x</code>, <code>y</code>, <code>w</code>, <code>h</code>) must be provided together or omitted.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Extract frame 1000 (full frame)</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/thumbnail?frame=1000"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span>-o<span class="w"> </span>frame_1000.jpg
|
||||
|
||||
<span class="c1"># Extract and crop face region (x=320, y=240, w=160, h=160)</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/thumbnail?frame=1000&x=320&y=240&w=160&h=160"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span>-o<span class="w"> </span>face_crop.jpg
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response</h4>
|
||||
<ul>
|
||||
<li><strong>200</strong>: <code>image/jpeg</code> binary data</li>
|
||||
<li><strong>404</strong>: File not found</li>
|
||||
<li><strong>500</strong>: FFmpeg error (e.g., frame number exceeds video duration)</li>
|
||||
</ul>
|
||||
<h3><code>GET /api/v1/file/:file_uuid/clip</code></h3>
|
||||
<p>Extract a video clip (time range) as MPEG-TS stream. Uses FFmpeg <code>-ss</code> fast seek.</p>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<h4>Query Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Default</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>start_frame</code></td>
|
||||
<td>integer</td>
|
||||
<td>No*</td>
|
||||
<td>—</td>
|
||||
<td>Start frame (zero-based). <strong>Frame-accurate</strong> — use this for precision.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>end_frame</code></td>
|
||||
<td>integer</td>
|
||||
<td>No*</td>
|
||||
<td>—</td>
|
||||
<td>End frame (zero-based, inclusive). Requires <code>start_frame</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>start_time</code></td>
|
||||
<td>float</td>
|
||||
<td>No*</td>
|
||||
<td>—</td>
|
||||
<td>Start time in seconds. Approximate (FPS-dependent). Fallback if frames not given.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>end_time</code></td>
|
||||
<td>float</td>
|
||||
<td>No*</td>
|
||||
<td>—</td>
|
||||
<td>End time in seconds. Approximate (FPS-dependent). Fallback if frames not given.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>fps</code></td>
|
||||
<td>float</td>
|
||||
<td>No</td>
|
||||
<td>video FPS</td>
|
||||
<td>Override frames-per-second for frame↔time calculation. Defaults to video's detected FPS.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>mode</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td><code>normal</code></td>
|
||||
<td><code>normal</code> or <code>debug</code> (draws "CLIP" overlay)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>audio</code></td>
|
||||
<td>string</td>
|
||||
<td>No</td>
|
||||
<td><code>on</code></td>
|
||||
<td><code>on</code> or <code>off</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Either (<code>start_frame</code>+<code>end_frame</code>) OR (<code>start_time</code>+<code>end_time</code>) must be provided.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="c1"># Clip by frame range (primary)</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/clip?start_frame=0&end_frame=47"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span>-o<span class="w"> </span>clip.ts
|
||||
|
||||
<span class="c1"># Clip by time range (fallback)</span>
|
||||
curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/clip?start_time=30&end_time=45"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span>-o<span class="w"> </span>clip.ts
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response</h4>
|
||||
<ul>
|
||||
<li><strong>200</strong>: <code>video/mp2t</code> MPEG-TS stream</li>
|
||||
<li><strong>400</strong>: Missing/invalid range parameters</li>
|
||||
<li><strong>404</strong>: File not found</li>
|
||||
<li><strong>500</strong>: FFmpeg error</li>
|
||||
</ul>
|
||||
<h4>Technical Notes</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Detail</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><strong>Backend</strong></td>
|
||||
<td>FFmpeg (<code>ffmpeg-full</code>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Seek</strong></td>
|
||||
<td><code>-ss</code> before <code>-i</code> (fast keyframe seek)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Format</strong></td>
|
||||
<td>MPEG-TS (<code>mpegts</code> muxer, pipe-safe)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Codec</strong></td>
|
||||
<td>H.264 + AAC</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Cache</strong></td>
|
||||
<td><code>Cache-Control: public, max-age=86400</code> (24h)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Detail</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><strong>Backend</strong></td>
|
||||
<td>FFmpeg (<code>ffmpeg-full</code>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Filter</strong></td>
|
||||
<td><code>select=eq(n\,FRAME)</code> to select frame, optional <code>crop=W:H:X:Y</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Output</strong></td>
|
||||
<td>Single JPEG via pipe (<code>image2pipe</code>, <code>mjpeg</code> codec)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Cache</strong></td>
|
||||
<td><code>Cache-Control: public, max-age=86400</code> (24h)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Frame number</strong></td>
|
||||
<td>Zero-based (<code>frame=0</code> = first frame of video)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,123 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>09 Tmdb - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: tmdb -->
|
||||
<!-- description: TMDb enrichment endpoints — prefetch, probe, resource, check -->
|
||||
<!-- depends: 01_auth, 03_register -->
|
||||
|
||||
<h2>TMDb Enrichment</h2>
|
||||
<blockquote>
|
||||
<p><strong>Offline operation</strong>: TMDb prefetch now checks local identity files first (<code>identities/_index.json</code> + <code>*.tmdb.json</code>).
|
||||
If local files exist, no external API call is made. Internet is only needed for initial data seeding.</p>
|
||||
</blockquote>
|
||||
<h3>Overview</h3>
|
||||
<p>TMDb enrichment is an optional identity enrichment step that can be run after Pipeline face detection completes. The workflow is:</p>
|
||||
<ol>
|
||||
<li><strong>Prefetch</strong> (requires internet): Download movie cast data from TMDb API → cache to <code>{file_uuid}.tmdb.json</code></li>
|
||||
<li><strong>Probe</strong>: Read local cache → create identities for <strong>all</strong> cast members (<code>source='tmdb'</code>) + save <code>identity.json</code> + download profile image to <code>{OUTPUT}/identities/{uuid}/profile.jpg</code></li>
|
||||
<li><strong>Match</strong>: The worker automatically matches video faces against TMDb identities when <code>MOMENTRY_TMDB_PROBE_ENABLED=true</code></li>
|
||||
</ol>
|
||||
<h3><code>POST /api/v1/agents/tmdb/prefetch</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Fetch TMDb cast data for a registered file and cache it locally. This is the only step requiring internet access.</p>
|
||||
<h4>Request Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>file_uuid</code></td>
|
||||
<td>string</td>
|
||||
<td>Yes</td>
|
||||
<td>File UUID to enrich</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/agents/tmdb/prefetch"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_uuid": "'</span><span class="s2">"</span><span class="nv">$FILE_UUID</span><span class="s2">"</span><span class="s1">'"}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"..."</span><span class="p">,</span><span class="w"> </span><span class="nt">"cache_path"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/output/...tmdb.json"</span><span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h3><code>POST /api/v1/file/:file_uuid/tmdb-probe</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: file-level</p>
|
||||
<p>Read local TMDb cache and create/update identities. Requires prefetch to have been run first.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/file/</span><span class="nv">$FILE_UUID</span><span class="s2">/tmdb-probe"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{identities_created, movie_title}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200 — identities created)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w"> </span><span class="nt">"identities_created"</span><span class="p">:</span><span class="w"> </span><span class="mi">15</span><span class="p">,</span><span class="w"> </span><span class="nt">"movie_title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Charade"</span><span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response (200 — no cache)</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"No TMDb cache found. Run tmdb-prefetch first."</span><span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h3><code>GET /api/v1/resource/tmdb</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: system-level</p>
|
||||
<p>View TMDb resource status including configuration, identity counts, and cache file count.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/resource/tmdb"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{identities_seeded, cache_files}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h3><code>POST /api/v1/resource/tmdb/check</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: system-level</p>
|
||||
<p>Ping the TMDb API to verify connectivity and measure latency.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/resource/tmdb/check"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'.status'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"api_key_configured"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"enabled"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"api_reachable"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"api_latency_ms"</span><span class="p">:</span><span class="w"> </span><span class="mi">120</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,364 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>10 Pipeline - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: pipeline -->
|
||||
<!-- description: Pipeline processors, ingestion status, stats endpoints -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
<h2>Pipeline</h2>
|
||||
<h3>Dependency Graph</h3>
|
||||
<div class="codehilite"><pre><span></span><code><span class="n">flowchart</span><span class="w"> </span><span class="n">TB</span>
|
||||
<span class="w"> </span><span class="n">subgraph</span><span class="w"> </span><span class="n">Processors</span><span class="p">[</span><span class="s">"10 Processors"</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">Cut</span><span class="p">[</span><span class="n">Cut</span><span class="p">]</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">ASR</span><span class="p">[</span><span class="n">ASR</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">ASR</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">ASRX</span><span class="p">[</span><span class="n">ASRX</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">ASRX</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Story</span><span class="p">[</span><span class="n">Story</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">Cut</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Story</span>
|
||||
<span class="w"> </span><span class="n">YOLO</span><span class="p">[</span><span class="n">YOLO</span><span class="p">]</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">VisualChunk</span><span class="p">[</span><span class="n">VisualChunk</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">VisualChunk</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Story</span>
|
||||
<span class="w"> </span><span class="n">Face</span><span class="p">[</span><span class="n">Face</span><span class="p">]</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Story</span>
|
||||
<span class="w"> </span><span class="n">Story</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">FiveW1H</span><span class="p">[</span><span class="mi">5</span><span class="n">W1H</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">OCR</span><span class="p">[</span><span class="n">OCR</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">Pose</span><span class="p">[</span><span class="n">Pose</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">end</span>
|
||||
|
||||
<span class="w"> </span><span class="n">subgraph</span><span class="w"> </span><span class="n">Ingestion</span><span class="p">[</span><span class="s">"入庫 (Post-Processing)"</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">ASR</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Rule1</span><span class="p">[</span><span class="n">Rule</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="n">Sentence</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">ASRX</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Rule1</span>
|
||||
<span class="w"> </span><span class="n">Rule1</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Vectorize</span><span class="p">[</span><span class="n">Auto</span><span class="o">-</span><span class="n">Vectorize</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">Rule1</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Phase1</span><span class="p">[</span><span class="n">Phase</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="n">Pack</span><span class="p">]</span>
|
||||
|
||||
<span class="w"> </span><span class="n">Cut</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Rule3</span><span class="p">[</span><span class="n">Rule</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="n">Scene</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">ASR</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Rule3</span>
|
||||
|
||||
<span class="w"> </span><span class="n">Face</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Trace</span><span class="p">[</span><span class="n">Face</span><span class="w"> </span><span class="n">Trace</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">Trace</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Qdrant</span><span class="p">[</span><span class="n">Qdrant</span><span class="w"> </span><span class="n">Sync</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">Trace</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">TraceChunks</span><span class="p">[</span><span class="n">Trace</span><span class="w"> </span><span class="n">Chunks</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">Trace</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">TKG</span><span class="p">[</span><span class="n">TKG</span><span class="w"> </span><span class="n">Builder</span><span class="p">]</span>
|
||||
|
||||
<span class="w"> </span><span class="n">Face</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">TMDbMatch</span><span class="p">[</span><span class="n">TMDb</span><span class="w"> </span><span class="n">Match</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">Face</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">SceneMeta</span><span class="p">[</span><span class="n">Scene</span><span class="w"> </span><span class="n">Metadata</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">YOLO</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">SceneMeta</span>
|
||||
<span class="w"> </span><span class="n">Face</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">IdentityAgent</span><span class="p">[</span><span class="n">Identity</span><span class="w"> </span><span class="n">Agent</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">ASRX</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">IdentityAgent</span>
|
||||
|
||||
<span class="w"> </span><span class="n">Cut</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Agent5W1H</span><span class="p">[</span><span class="mi">5</span><span class="n">W1H</span><span class="w"> </span><span class="n">Agent</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">ASR</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Agent5W1H</span>
|
||||
<span class="w"> </span><span class="n">Agent5W1H</span><span class="w"> </span><span class="o">--></span><span class="w"> </span><span class="n">Phase2</span><span class="p">[</span><span class="n">Phase</span><span class="w"> </span><span class="mi">2</span><span class="w"> </span><span class="n">Pack</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="n">end</span>
|
||||
|
||||
<span class="w"> </span><span class="n">style</span><span class="w"> </span><span class="n">Processors</span><span class="w"> </span><span class="n">fill</span><span class="o">:</span><span class="err">#</span><span class="mi">1</span><span class="n">a1a2e</span><span class="p">,</span><span class="n">stroke</span><span class="o">:</span><span class="err">#</span><span class="n">e94560</span>
|
||||
<span class="w"> </span><span class="n">style</span><span class="w"> </span><span class="n">Ingestion</span><span class="w"> </span><span class="n">fill</span><span class="o">:</span><span class="err">#</span><span class="mi">16213</span><span class="n">e</span><span class="p">,</span><span class="n">stroke</span><span class="o">:</span><span class="err">#</span><span class="mf">0f</span><span class="mi">3460</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h3>Pipeline Completion Flow</h3>
|
||||
<p>The pipeline is <strong>not complete</strong> until both the 10 processors AND the 入庫 (ingestion) steps have finished. The worker polls every 3 seconds and only marks the job as <code>completed</code> when all ingestion steps verify OK.</p>
|
||||
<div class="codehilite"><pre><span></span><code><span class="mf">10</span><span class="w"> </span><span class="n">processors</span><span class="w"> </span><span class="n">done</span>
|
||||
<span class="w"> </span><span class="err">↓</span><span class="w"> </span><span class="p">(</span><span class="n">job</span><span class="w"> </span><span class="n">status</span><span class="w"> </span><span class="n">stays</span><span class="w"> </span><span class="s">"running"</span><span class="p">)</span>
|
||||
<span class="n">Algorithm</span><span class="w"> </span><span class="mf">1</span><span class="w"> </span><span class="n">Trigger</span><span class="p">:</span><span class="w"> </span><span class="n">Rule</span><span class="w"> </span><span class="mf">1</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">Vectorize</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">Phase</span><span class="w"> </span><span class="mf">1</span><span class="w"> </span><span class="n">Pack</span>
|
||||
<span class="w"> </span><span class="err">↓</span><span class="w"> </span><span class="p">(</span><span class="n">job</span><span class="w"> </span><span class="kr">run</span><span class="n">s</span><span class="w"> </span><span class="n">in</span><span class="w"> </span><span class="n">parallel</span><span class="p">)</span>
|
||||
<span class="n">Algorithm</span><span class="w"> </span><span class="mf">2</span><span class="w"> </span><span class="n">Trigger</span><span class="p">:</span><span class="w"> </span><span class="n">Face</span><span class="w"> </span><span class="n">Trace</span><span class="w"> </span><span class="err">→</span><span class="w"> </span><span class="n">TKG</span><span class="p">,</span><span class="w"> </span><span class="n">Scene</span><span class="w"> </span><span class="n">Metadata</span><span class="p">,</span><span class="w"> </span><span class="n">Identity</span><span class="w"> </span><span class="n">Agent</span><span class="p">,</span><span class="w"> </span><span class="mf">5</span><span class="n">W1H</span><span class="w"> </span><span class="n">Agent</span>
|
||||
<span class="w"> </span><span class="err">↓</span><span class="w"> </span><span class="p">(</span><span class="n">poll</span><span class="w"> </span><span class="n">checks</span><span class="w"> </span><span class="n">every</span><span class="w"> </span><span class="mf">3</span><span class="n">s</span><span class="p">)</span>
|
||||
<span class="n">Ingestion</span><span class="w"> </span><span class="n">verification</span><span class="p">:</span><span class="w"> </span><span class="n">rule1</span><span class="w"> </span><span class="err">✓</span><span class="w"> </span><span class="n">vectorize</span><span class="w"> </span><span class="err">✓</span><span class="w"> </span><span class="n">rule3</span><span class="w"> </span><span class="err">✓</span><span class="w"> </span><span class="n">face_trace</span><span class="w"> </span><span class="err">✓</span><span class="w"> </span><span class="n">tkg</span><span class="w"> </span><span class="err">✓</span><span class="w"> </span><span class="n">scene_meta</span><span class="w"> </span><span class="err">✓</span><span class="w"> </span><span class="mf">5</span><span class="n">w1h</span><span class="w"> </span><span class="err">✓</span>
|
||||
<span class="w"> </span><span class="err">↓</span>
|
||||
<span class="n">job</span><span class="w"> </span><span class="n">status</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"completed"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h3>10 Processor Stages</h3>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>#</th>
|
||||
<th>Processor</th>
|
||||
<th>Depends On</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>1</td>
|
||||
<td><code>Cut</code></td>
|
||||
<td>—</td>
|
||||
<td>Scene boundary detection (PySceneDetect)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>2</td>
|
||||
<td><code>ASR</code></td>
|
||||
<td>Cut</td>
|
||||
<td>Automatic speech recognition (faster-whisper)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>3</td>
|
||||
<td><code>ASRX</code></td>
|
||||
<td>ASR</td>
|
||||
<td>Speaker diarization + ASR refinement</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>4</td>
|
||||
<td><code>YOLO</code></td>
|
||||
<td>—</td>
|
||||
<td>Object detection (YOLOv8)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>5</td>
|
||||
<td><code>OCR</code></td>
|
||||
<td>—</td>
|
||||
<td>Optical character recognition</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>6</td>
|
||||
<td><code>Face</code></td>
|
||||
<td>—</td>
|
||||
<td>Face detection + recognition (InsightFace + CoreML)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>7</td>
|
||||
<td><code>Pose</code></td>
|
||||
<td>—</td>
|
||||
<td>Pose estimation</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>8</td>
|
||||
<td><code>VisualChunk</code></td>
|
||||
<td>YOLO</td>
|
||||
<td>Visual object chunking</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>9</td>
|
||||
<td><code>Story</code></td>
|
||||
<td>ASRX + Cut + YOLO + Face</td>
|
||||
<td>Narrative scene summarization (LLM, with embedding)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>10</td>
|
||||
<td><code>5W1H</code></td>
|
||||
<td>Story</td>
|
||||
<td>Who/What/When/Where/Why extraction (LLM, with embedding)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3>入庫 (Post-Processing / Ingestion)</h3>
|
||||
<p>These steps run after the 10 processors and are <strong>required for pipeline completion</strong>. The worker checks all of them before marking the job as done.</p>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>#</th>
|
||||
<th>Step</th>
|
||||
<th>Triggers When</th>
|
||||
<th>Verification</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>1</td>
|
||||
<td><strong>Rule 1 Sentence Chunking</strong></td>
|
||||
<td>ASR + ASRX done</td>
|
||||
<td><code>chunk</code> table has rows with <code>chunk_type = 'sentence'</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>2</td>
|
||||
<td><strong>Auto-Vectorize</strong></td>
|
||||
<td>Rule 1 done</td>
|
||||
<td><code>chunk.embedding</code> IS NOT NULL for sentence chunks</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>3</td>
|
||||
<td><strong>Phase 1 Pack</strong></td>
|
||||
<td>Rule 1 done</td>
|
||||
<td><code>release_pack.py --phase 1</code> executed</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>4</td>
|
||||
<td><strong>Rule 3 Scene Chunking</strong></td>
|
||||
<td>All 10 processors done + Cut + ASR</td>
|
||||
<td><code>chunk</code> table has rows with <code>chunk_type = 'cut'</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>5</td>
|
||||
<td><strong>Face Trace</strong></td>
|
||||
<td>All 10 processors done + Face</td>
|
||||
<td><code>face_detections.trace_id</code> IS NOT NULL</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>6</td>
|
||||
<td><strong>Qdrant Face Sync</strong></td>
|
||||
<td>Face Trace done</td>
|
||||
<td>Qdrant face_embedding collection populated</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>7</td>
|
||||
<td><strong>Trace Chunks</strong></td>
|
||||
<td>Face Trace done</td>
|
||||
<td><code>chunk</code> table has rows with <code>chunk_type = 'trace'</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>8</td>
|
||||
<td><strong>TKG Builder</strong></td>
|
||||
<td>Face Trace done</td>
|
||||
<td><code>tkg_nodes</code> + <code>tkg_edges</code> tables have rows</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>9</td>
|
||||
<td><strong>TMDb Face Matching</strong></td>
|
||||
<td>TMDb enabled + Face done</td>
|
||||
<td><code>face_detections.identity_id</code> IS NOT NULL</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>10</td>
|
||||
<td><strong>Heuristic Scene Metadata</strong></td>
|
||||
<td>Face + YOLO done</td>
|
||||
<td><code>{file_uuid}.scene_meta.json</code> exists on disk</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>11</td>
|
||||
<td><strong>Identity Agent</strong></td>
|
||||
<td>Face + ASRX done</td>
|
||||
<td><code>identities</code> with <code>source = 'identity_agent'</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>12</td>
|
||||
<td><strong>5W1H Agent</strong></td>
|
||||
<td>Cut + ASR done</td>
|
||||
<td><code>chunk.summary_text</code> IS NOT NULL for cut chunks</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>13</td>
|
||||
<td><strong>Release Pack</strong></td>
|
||||
<td>5W1H Agent done</td>
|
||||
<td><code>release_pack.py --phase 2</code> executed</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3>Ingestion Status</h3>
|
||||
<p>Check real-time ingestion status for a file:</p>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/stats/ingestion-status/{file_uuid}"</span>
|
||||
</code></pre></div>
|
||||
|
||||
<p>Returns per-step <code>done</code> / <code>pending</code> status with detail counts.</p>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span><span class="s2">"http://localhost:3003/api/v1/stats/ingestion-status/bd80fec9c42afb0307eb28f22c64c76a"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'.steps[] | {name, status, detail}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h4>Response</h4>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"bd80fec9c42afb0307eb28f22c64c76a"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"steps"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"rule1_sentence"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pending"</span><span class="p">,</span><span class="w"> </span><span class="nt">"detail"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0 sentence chunks"</span><span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auto_vectorize"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pending"</span><span class="p">,</span><span class="w"> </span><span class="nt">"detail"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0 embedded"</span><span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"rule3_scene"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pending"</span><span class="p">,</span><span class="w"> </span><span class="nt">"detail"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0 scene chunks"</span><span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"face_trace"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pending"</span><span class="p">,</span><span class="w"> </span><span class="nt">"detail"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0 traces"</span><span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"trace_chunks"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pending"</span><span class="p">,</span><span class="w"> </span><span class="nt">"detail"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0 trace chunks"</span><span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"tkg"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pending"</span><span class="p">,</span><span class="w"> </span><span class="nt">"detail"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0 nodes, 0 edges"</span><span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"identity_match"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pending"</span><span class="p">,</span><span class="w"> </span><span class="nt">"detail"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0 identities"</span><span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"scene_metadata"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pending"</span><span class="p">,</span><span class="w"> </span><span class="nt">"detail"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w"> </span><span class="p">},</span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"5w1h"</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pending"</span><span class="p">,</span><span class="w"> </span><span class="nt">"detail"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0 scenes with 5W1H"</span><span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">]</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h3>Stats Endpoints</h3>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Method</th>
|
||||
<th>Endpoint</th>
|
||||
<th>Auth</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>GET</td>
|
||||
<td><code>/api/v1/stats/sftpgo</code></td>
|
||||
<td>No</td>
|
||||
<td>SFTPGo service status</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>GET</td>
|
||||
<td><code>/api/v1/stats/ingestion-status/:file_uuid</code></td>
|
||||
<td>No</td>
|
||||
<td>Per-file ingestion checklist</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3>Configuration</h3>
|
||||
<h3><code>POST /api/v1/config/cache</code></h3>
|
||||
<p><strong>Auth</strong>: Required
|
||||
<strong>Scope</strong>: system-level</p>
|
||||
<p>Toggle the Redis cache on or off.</p>
|
||||
<h4>Request Parameters</h4>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>enabled</code></td>
|
||||
<td>boolean</td>
|
||||
<td>Yes</td>
|
||||
<td><code>true</code> to enable, <code>false</code> to disable</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>Example</h4>
|
||||
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/config/cache"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
||||
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"enabled": false}'</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h3>Unmounted Routes</h3>
|
||||
<p>The following routes are defined in source code but are <strong>NOT</strong> currently mounted in the router:</p>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Endpoint</th>
|
||||
<th>Source file</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>/api/v1/search/persons</code></td>
|
||||
<td><code>universal_search.rs</code> (not mounted)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>/api/v1/who</code></td>
|
||||
<td><code>who.rs</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>/api/v1/who/candidates</code></td>
|
||||
<td><code>who.rs</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,207 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>12 Agent - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<h1>Agent Endpoints</h1>
|
||||
<p>Agent endpoints provide AI-powered capabilities including translation, identity analysis, and 5W1H extraction.</p>
|
||||
<h2>POST /api/v1/agents/translate</h2>
|
||||
<p>Translate text between languages using Gemma4 (llama.cpp, port 8082).</p>
|
||||
<h3>Request</h3>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"text"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Hello, welcome to Momentry Core."</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"target_language"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Traditional Chinese"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"source_language"</span><span class="p">:</span><span class="w"> </span><span class="s2">"English"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>text</code></td>
|
||||
<td>string</td>
|
||||
<td>✅</td>
|
||||
<td>Text to translate</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>target_language</code></td>
|
||||
<td>string</td>
|
||||
<td>✅</td>
|
||||
<td>Target language name (e.g. "Traditional Chinese", "Japanese")</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>source_language</code></td>
|
||||
<td>string</td>
|
||||
<td>❌</td>
|
||||
<td>Source language (default: "auto")</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3>Response</h3>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"translated_text"</span><span class="p">:</span><span class="w"> </span><span class="s2">"您好，歡迎使用 Momentry Core。"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"source_language_detected"</span><span class="p">:</span><span class="w"> </span><span class="s2">"English"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"model_used"</span><span class="p">:</span><span class="w"> </span><span class="s2">"google_gemma-4-26B-A4B-it-Q5_K_M.gguf"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h3>Supported Language Pairs (tested)</h3>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Source</th>
|
||||
<th>Target</th>
|
||||
<th>Quality</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>English</td>
|
||||
<td>Traditional Chinese</td>
|
||||
<td>✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>English</td>
|
||||
<td>Japanese</td>
|
||||
<td>✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Chinese</td>
|
||||
<td>English</td>
|
||||
<td>✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>English</td>
|
||||
<td>French</td>
|
||||
<td>✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Chinese</td>
|
||||
<td>Japanese</td>
|
||||
<td>✅</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3>Model</h3>
|
||||
<ul>
|
||||
<li><strong>Model</strong>: Gemma4 26B (Q5_K_M)</li>
|
||||
<li><strong>Engine</strong>: llama.cpp at <code>localhost:8082</code></li>
|
||||
<li><strong>Endpoint</strong>: <code>/v1/chat/completions</code> (OpenAI-compatible)</li>
|
||||
<li><strong>Temperature</strong>: 0.1</li>
|
||||
<li><strong>Max tokens</strong>: 1024</li>
|
||||
</ul>
|
||||
<h3>Errors</h3>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Status</th>
|
||||
<th>Condition</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>500</td>
|
||||
<td>LLM unreachable or response parse failure</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>401</td>
|
||||
<td>Missing/invalid auth</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h2>POST /api/v1/agents/5w1h/analyze</h2>
|
||||
<p>Extract 5W1H (Who, What, When, Where, Why, How) from a scene. Uses Gemma4 LLM on port 8082.</p>
|
||||
<h3>Request</h3>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3abeee81d94597629ed8cb943f182e94"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"scene_id"</span><span class="p">:</span><span class="w"> </span><span class="mi">42</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h3>Response</h3>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"5w1h"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"who"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"Cary Grant"</span><span class="p">],</span>
|
||||
<span class="w"> </span><span class="nt">"what"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"discussing plans"</span><span class="p">],</span>
|
||||
<span class="w"> </span><span class="nt">"when"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"1963"</span><span class="p">],</span>
|
||||
<span class="w"> </span><span class="nt">"where"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"Paris"</span><span class="p">],</span>
|
||||
<span class="w"> </span><span class="nt">"why"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"vacation"</span><span class="p">],</span>
|
||||
<span class="w"> </span><span class="nt">"how"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"in person"</span><span class="p">]</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h2>POST /api/v1/agents/5w1h/batch</h2>
|
||||
<p>Batch analyze all scenes in a file for 5W1H extraction. Uses the pipeline's <code>parent_chunk_5w1h.py --mode llm</code>.</p>
|
||||
<h3>Request</h3>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3abeee81d94597629ed8cb943f182e94"</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h2>GET /api/v1/agents/5w1h/status</h2>
|
||||
<p>Get status of the 5W1H agent pipeline for a file.</p>
|
||||
<hr />
|
||||
<h2>Embedding Model</h2>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Detail</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><strong>Model</strong></td>
|
||||
<td>EmbeddingGemma-300m</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Endpoint</strong></td>
|
||||
<td><code>POST /v1/embeddings</code> on port 11436</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Dimension</strong></td>
|
||||
<td>768</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Used by</strong></td>
|
||||
<td><code>parent_chunk_5w1h.py --embed</code>, story, 5W1H, search</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,29 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-TW">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Momentry API 文件</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 900px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 28px; margin-bottom: 8px; }
|
||||
p.subtitle { color: #666; margin-bottom: 24px; }
|
||||
table { width: 100%; border-collapse: collapse; }
|
||||
tr { border-bottom: 1px solid #eee; }
|
||||
tr:last-child { border: none; }
|
||||
td { padding: 10px 0; }
|
||||
td.cn { width: 140px; font-weight: 600; color: #333; }
|
||||
td.en { color: #666; font-size: 14px; }
|
||||
a { color: #0066cc; text-decoration: none; display: block; }
|
||||
a:hover td { background: #f8f8f8; border-radius: 4px; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<h1>Momentry API 文件</h1>
|
||||
<p class="subtitle">API 參考手冊 — 登入後可瀏覽各模組文件</p>
|
||||
<table><tr onclick="window.location='01_auth.html'" style="cursor:pointer"><td class="cn">安全認證</td><td class="en">Authentication</td></tr><tr onclick="window.location='02_health.html'" style="cursor:pointer"><td class="cn">健康檢查</td><td class="en">Health</td></tr><tr onclick="window.location='03_register.html'" style="cursor:pointer"><td class="cn">檔案註冊</td><td class="en">File Registration</td></tr><tr onclick="window.location='04_lookup.html'" style="cursor:pointer"><td class="cn">檔案屬性查詢</td><td class="en">File Lookup</td></tr><tr onclick="window.location='05_process.html'" style="cursor:pointer"><td class="cn">處理流程</td><td class="en">Processing</td></tr><tr onclick="window.location='06_search.html'" style="cursor:pointer"><td class="cn">搜尋功能</td><td class="en">Search</td></tr><tr onclick="window.location='07_identity.html'" style="cursor:pointer"><td class="cn">身份識別</td><td class="en">Identity</td></tr><tr onclick="window.location='08_identity_agent.html'" style="cursor:pointer"><td class="cn">智能身份綁定</td><td class="en">Smart Identity Binding</td></tr><tr onclick="window.location='08_media.html'" style="cursor:pointer"><td class="cn">串流與截圖</td><td class="en">Streaming & Thumbnails</td></tr><tr onclick="window.location='09_tmdb.html'" style="cursor:pointer"><td class="cn">TMDb 整合</td><td class="en">TMDb Integration</td></tr><tr onclick="window.location='10_pipeline.html'" style="cursor:pointer"><td class="cn">生產線</td><td class="en">Pipeline</td></tr><tr onclick="window.location='12_agent.html'" style="cursor:pointer"><td class="cn">智慧代理</td><td class="en">AI Agents</td></tr></table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,46 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Login - Momentry Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; display: flex; justify-content: center; align-items: center; height: 100vh; }
|
||||
.card { background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; width: 360px; }
|
||||
h1 { font-size: 24px; margin-bottom: 24px; text-align: center; }
|
||||
input { width: 100%; padding: 10px 12px; margin-bottom: 12px; border: 1px solid #ddd; border-radius: 6px; font-size: 14px; }
|
||||
button { width: 100%; padding: 10px; background: #0066cc; color: white; border: none; border-radius: 6px; font-size: 16px; cursor: pointer; }
|
||||
button:hover { background: #0052a3; }
|
||||
.error { color: #cc0000; font-size: 13px; margin-bottom: 12px; display: none; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="card">
|
||||
<h1>Momentry Docs</h1>
|
||||
<form id="loginForm">
|
||||
<input type="text" id="username" placeholder="Username" value="demo" required>
|
||||
<input type="password" id="password" placeholder="Password" value="demo" required>
|
||||
<div class="error" id="error">Invalid credentials</div>
|
||||
<button type="submit">Login</button>
|
||||
</form>
|
||||
</div>
|
||||
<script>
|
||||
document.getElementById('loginForm').onsubmit = async function(e) {
|
||||
e.preventDefault();
|
||||
const resp = await fetch('/api/v1/auth/login', {
|
||||
method: 'POST',
|
||||
headers: {'Content-Type': 'application/json'},
|
||||
body: JSON.stringify({
|
||||
username: document.getElementById('username').value,
|
||||
password: document.getElementById('password').value
|
||||
})
|
||||
});
|
||||
if (resp.ok) {
|
||||
window.location.href = '/doc/index.html';
|
||||
} else {
|
||||
document.getElementById('error').style.display = 'block';
|
||||
}
|
||||
};
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,180 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>11 Error Codes - Momentry API Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 24px; margin: 24px 0 12px; }
|
||||
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
||||
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
||||
p { line-height: 1.6; margin: 8px 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||||
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
||||
th { background: #f0f0f0; font-weight: 600; }
|
||||
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
||||
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
||||
pre code { background: none; padding: 0; }
|
||||
a { color: #0066cc; }
|
||||
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
||||
.back:hover { color: #333; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
<!-- module: error_codes -->
|
||||
<!-- description: Standard API error codes -->
|
||||
<!-- depends: -->
|
||||
|
||||
<h2>Error Response Format</h2>
|
||||
<p>All API errors follow this JSON structure:</p>
|
||||
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"error"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"code"</span><span class="p">:</span><span class="w"> </span><span class="s2">"E001_NOT_FOUND"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Resource not found"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"details"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="nt">"resource"</span><span class="p">:</span><span class="w"> </span><span class="s2">"file_uuid"</span><span class="p">,</span><span class="w"> </span><span class="nt">"value"</span><span class="p">:</span><span class="w"> </span><span class="s2">"abc"</span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div>
|
||||
|
||||
<h2>Error Code List</h2>
|
||||
<h3>Generic Errors (E0xx)</h3>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Code</th>
|
||||
<th>HTTP</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>E001_NOT_FOUND</code></td>
|
||||
<td>404</td>
|
||||
<td>Resource not found (file, identity, chunk)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E002_DUPLICATE</code></td>
|
||||
<td>409</td>
|
||||
<td>Resource already exists</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E003_VALIDATION</code></td>
|
||||
<td>400</td>
|
||||
<td>Request parameter validation failed</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E004_UNAUTHORIZED</code></td>
|
||||
<td>401</td>
|
||||
<td>Invalid API key or token</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E005_INTERNAL</code></td>
|
||||
<td>500</td>
|
||||
<td>Internal server error</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3>Processor Errors (E1xx)</h3>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Code</th>
|
||||
<th>HTTP</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>E101_PROCESSOR_FAIL</code></td>
|
||||
<td>500</td>
|
||||
<td>Python script execution failed</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E102_TIMEOUT</code></td>
|
||||
<td>504</td>
|
||||
<td>Processing timeout</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E103_RESUME_FAIL</code></td>
|
||||
<td>500</td>
|
||||
<td>Resume failed (checkpoint not found)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E104_NO_VIDEO</code></td>
|
||||
<td>400</td>
|
||||
<td>Video file path not found</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3>Identity Errors (E2xx)</h3>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Code</th>
|
||||
<th>HTTP</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>E201_FACE_NOT_FOUND</code></td>
|
||||
<td>404</td>
|
||||
<td>Face detection not found</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E202_MERGE_CONFLICT</code></td>
|
||||
<td>409</td>
|
||||
<td>Identity merge conflict</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E203_CANDIDATE_EMPTY</code></td>
|
||||
<td>404</td>
|
||||
<td>No candidates available for confirmation</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3>TMDb Errors (E3xx)</h3>
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Code</th>
|
||||
<th>HTTP</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>E301_TMDB_NO_KEY</code></td>
|
||||
<td>400</td>
|
||||
<td><code>TMDB_API_KEY</code> environment variable not set</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E302_TMDB_UNREACHABLE</code></td>
|
||||
<td>502</td>
|
||||
<td>TMDb API unreachable or timed out</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E303_TMDB_CACHE_NOT_FOUND</code></td>
|
||||
<td>200</td>
|
||||
<td>No local TMDb cache; run prefetch first</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E304_TMDB_PROBE_FAILED</code></td>
|
||||
<td>500</td>
|
||||
<td>TMDb probe execution failed</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>E305_TMDB_MOVIE_NOT_FOUND</code></td>
|
||||
<td>404</td>
|
||||
<td>No matching TMDb movie found from filename</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,29 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-TW">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Momentry API 文件</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
||||
.container { max-width: 900px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
||||
h1 { font-size: 28px; margin-bottom: 8px; }
|
||||
p.subtitle { color: #666; margin-bottom: 24px; }
|
||||
table { width: 100%; border-collapse: collapse; }
|
||||
tr { border-bottom: 1px solid #eee; }
|
||||
tr:last-child { border: none; }
|
||||
td { padding: 10px 0; }
|
||||
td.cn { width: 140px; font-weight: 600; color: #333; }
|
||||
td.en { color: #666; font-size: 14px; }
|
||||
a { color: #0066cc; text-decoration: none; display: block; }
|
||||
a:hover td { background: #f8f8f8; border-radius: 4px; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<h1>Momentry API 文件</h1>
|
||||
<p class="subtitle">API 參考手冊 — 登入後可瀏覽各模組文件</p>
|
||||
<table><tr onclick="window.location='11_error_codes.html'" style="cursor:pointer"><td class="cn">錯誤碼</td><td class="en">Error Codes</td></tr></table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,46 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Login - Momentry Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; display: flex; justify-content: center; align-items: center; height: 100vh; }
|
||||
.card { background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; width: 360px; }
|
||||
h1 { font-size: 24px; margin-bottom: 24px; text-align: center; }
|
||||
input { width: 100%; padding: 10px 12px; margin-bottom: 12px; border: 1px solid #ddd; border-radius: 6px; font-size: 14px; }
|
||||
button { width: 100%; padding: 10px; background: #0066cc; color: white; border: none; border-radius: 6px; font-size: 16px; cursor: pointer; }
|
||||
button:hover { background: #0052a3; }
|
||||
.error { color: #cc0000; font-size: 13px; margin-bottom: 12px; display: none; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="card">
|
||||
<h1>Momentry Docs</h1>
|
||||
<form id="loginForm">
|
||||
<input type="text" id="username" placeholder="Username" value="demo" required>
|
||||
<input type="password" id="password" placeholder="Password" value="demo" required>
|
||||
<div class="error" id="error">Invalid credentials</div>
|
||||
<button type="submit">Login</button>
|
||||
</form>
|
||||
</div>
|
||||
<script>
|
||||
document.getElementById('loginForm').onsubmit = async function(e) {
|
||||
e.preventDefault();
|
||||
const resp = await fetch('/api/v1/auth/login', {
|
||||
method: 'POST',
|
||||
headers: {'Content-Type': 'application/json'},
|
||||
body: JSON.stringify({
|
||||
username: document.getElementById('username').value,
|
||||
password: document.getElementById('password').value
|
||||
})
|
||||
});
|
||||
if (resp.ok) {
|
||||
window.location.href = '/doc/index.html';
|
||||
} else {
|
||||
document.getElementById('error').style.display = 'block';
|
||||
}
|
||||
};
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,280 +0,0 @@
|
||||
<!-- module: auth -->
|
||||
<!-- description: Authentication — login, logout, JWT, session cookie, API key -->
|
||||
<!-- depends: -->
|
||||
|
||||
## Base URL
|
||||
|
||||
| Environment | URL | Purpose |
|
||||
|-------------|-----|---------|
|
||||
| Production | `http://localhost:3002` | Production deployment |
|
||||
| External (M5) | `https://m5api.momentry.ddns.net` | Remote access |
|
||||
|
||||
## Variables
|
||||
|
||||
All examples in this documentation use these environment variables:
|
||||
|
||||
```bash
|
||||
API="http://localhost:3002"
|
||||
KEY="your-api-key-here"
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints under `/api/v1/*` require authentication.
|
||||
The following endpoints are public (no auth needed):
|
||||
|
||||
- `GET /health`
|
||||
- `POST /api/v1/auth/login`
|
||||
- `POST /api/v1/auth/logout`
|
||||
|
||||
### Three Authentication Modes
|
||||
|
||||
The system supports three authentication methods, checked in **priority order** by the middleware:
|
||||
|
||||
```
|
||||
Middleware priority:
|
||||
1. Session Cookie (Portal/browser)
|
||||
2. JWT Bearer (API clients, CLI)
|
||||
3. API Key Header (legacy compatibility)
|
||||
4. API Key Query Param (?api_key=)
|
||||
```
|
||||
|
||||
| Mode | Transport | Expiry | Scope | Best for |
|
||||
|------|-----------|--------|-------|----------|
|
||||
| **Session Cookie** | `Cookie: session_id=<session_id>` | 24h | per-browser session | Portal (browser) |
|
||||
| **JWT** | `Authorization: Bearer <token>` | 1h | per-login token | API clients, CLI, scripts |
|
||||
| **API Key** | `X-API-Key: <key>` | 90d | fixed key for automation | Legacy scripts, WordPress |
|
||||
|
||||
---
|
||||
|
||||
### Login
|
||||
|
||||
**Default accounts & API keys:**
|
||||
|
||||
| Username | Password | API Key | Role |
|
||||
|----------|----------|---------|------|
|
||||
| `admin` | `admin` | — | admin |
|
||||
| `demo` | `demo` | `muser_demo_key_32chars_abcdef1234567890` | user |
|
||||
|
||||
The demo API key is set via `MOMENTRY_DEMO_API_KEY` env var and can be used in place of JWT for marcom integrations:
|
||||
|
||||
```bash
|
||||
# Using API key instead of JWT
|
||||
curl -s "$API/api/v1/files/scan" -H "X-API-Key: muser_demo_key_32chars_abcdef1234567890"
|
||||
```
|
||||
|
||||
```bash
|
||||
# Login as admin
|
||||
curl -s -X POST "$API/api/v1/auth/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username": "admin", "password": "admin"}'
|
||||
|
||||
# Login as demo user
|
||||
curl -s -X POST "$API/api/v1/auth/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username": "demo", "password": "demo"}'
|
||||
```
|
||||
|
||||
#### Success Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"jwt": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"api_key": "muser_...",
|
||||
"user": {
|
||||
"username": "admin",
|
||||
"role": "admin"
|
||||
},
|
||||
"expires_at": "2026-05-18T13:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `jwt` | string | JWT access token. Use as `Authorization: Bearer <jwt>`. Expires in 1 hour. |
|
||||
| `api_key` | string | Legacy API key. Use as `X-API-Key: <key>`. Good for 90 days. |
|
||||
| `user.username` | string | Username |
|
||||
| `user.role` | string | Role: `admin`, `user`, or `readonly` |
|
||||
| `expires_at` | string | ISO8601 timestamp of JWT expiration |
|
||||
|
||||
The login endpoint also sets a `Set-Cookie` header for browser-based clients:
|
||||
|
||||
```
|
||||
Set-Cookie: session_id=<session_id>; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400
|
||||
```
|
||||
|
||||
#### Error Response (401)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Invalid username or password"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Using JWT
|
||||
|
||||
JWT is preferred for API clients (CLI scripts, WordPress). It is validated by the middleware without a database lookup (stateless).
|
||||
|
||||
```bash
|
||||
# Login and capture JWT
|
||||
JWT=$(curl -s -X POST "$API/api/v1/auth/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin"}' | python3 -c "import json,sys;print(json.load(sys.stdin)['jwt'])")
|
||||
|
||||
# Use JWT for all subsequent requests
|
||||
curl -H "Authorization: Bearer $JWT" "$API/api/v1/files/scan"
|
||||
curl -H "Authorization: Bearer $JWT" "$API/api/v1/resource/tmdb"
|
||||
```
|
||||
|
||||
JWT is short-lived (1 hour). When it expires, request a new one via login.
|
||||
|
||||
---
|
||||
|
||||
### Using Session Cookie (Browser)
|
||||
|
||||
Browser-based clients (Portal) get a session cookie automatically after login. The browser sends the cookie with every request—no manual header needed.
|
||||
|
||||
```bash
|
||||
# Login captures the session cookie from Set-Cookie header
|
||||
curl -v -X POST "$API/api/v1/auth/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin"}' 2>&1 | grep "Set-Cookie"
|
||||
|
||||
# Browser automatically sends: Cookie: session_id=<session_id>
|
||||
# No manual header needed for subsequent requests
|
||||
```
|
||||
|
||||
The session cookie is HttpOnly (not accessible from JavaScript) and SameSite=Strict (protected against CSRF).
|
||||
|
||||
---
|
||||
|
||||
### Using Legacy API Key
|
||||
|
||||
```bash
|
||||
curl -H "X-API-Key: $KEY" "$API/api/v1/files/scan"
|
||||
|
||||
# Also accepted via Bearer header (non-JWT format) or query parameter:
|
||||
curl -H "Authorization: Bearer $KEY" "$API/api/v1/files/scan"
|
||||
curl "$API/api/v1/files/scan?api_key=$KEY"
|
||||
```
|
||||
|
||||
API keys are validated via SHA256 hash lookup in the database. They are long-lived (90 days) and intended for automation.
|
||||
|
||||
### Obtaining an API Key (CLI)
|
||||
|
||||
```bash
|
||||
momentry api-key create "My API Key" --key-type user
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Logout
|
||||
|
||||
```bash
|
||||
# Logout using the session cookie (browser)
|
||||
curl -X POST "$API/api/v1/auth/logout" \
|
||||
-H "Cookie: session_id=<uuid>"
|
||||
```
|
||||
|
||||
#### What logout does
|
||||
|
||||
| Auth mode | Effect |
|
||||
|-----------|--------|
|
||||
| **Session Cookie** | Session deleted from database. Same cookie returns 401 on subsequent requests. |
|
||||
| **JWT** | JWT remains valid until expiry. (JWT is stateless — logout adds JWT to a blacklist only if API key mode is used.) |
|
||||
| **API Key** | API key remains valid. (Legacy keys are shared across sessions — revoking would break other clients.) |
|
||||
|
||||
#### Example: full session lifecycle
|
||||
|
||||
```bash
|
||||
# 1. Login
|
||||
SESSION_ID=$(curl -s -D - -X POST "$API/api/v1/auth/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin"}' | grep "Set-Cookie" | sed 's/.*session_id=\([^;]*\).*/\1/')
|
||||
|
||||
# 2. Use session (works)
|
||||
curl -s -o /dev/null -w "HTTP %{http_code}\n" "$API/api/v1/resource/tmdb" \
|
||||
-H "Cookie: session_id=$SESSION_ID"
|
||||
# → HTTP 200
|
||||
|
||||
# 3. Logout
|
||||
curl -s -X POST "$API/api/v1/auth/logout" \
|
||||
-H "Cookie: session_id=$SESSION_ID"
|
||||
# → {"success": true}
|
||||
|
||||
# 4. Use session again (rejected)
|
||||
curl -s -o /dev/null -w "HTTP %{http_code}\n" "$API/api/v1/resource/tmdb" \
|
||||
-H "Cookie: session_id=$SESSION_ID"
|
||||
# → HTTP 401
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Authentication Flow Summary
|
||||
|
||||
```
|
||||
Login Request
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ 1. Check users │ ← users table (argon2 password verify)
|
||||
│ table │
|
||||
└──────┬───────────┘
|
||||
│
|
||||
┌───┴───┐
|
||||
│ match │
|
||||
└───┬───┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ 2. Create JWT │ ← 1h expiry, signed with JWT_SECRET
|
||||
├──────────────────┤
|
||||
│ 3. Create │ ← 24h expiry, stored in sessions table
|
||||
│ session │
|
||||
├──────────────────┤
|
||||
│ 4. Set-Cookie │ ← HttpOnly, SameSite=Strict, Path=/
|
||||
├──────────────────┤
|
||||
│ 5. Return │ ← JWT + api_key + user info to client
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
```
|
||||
Protected Request
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Middleware checks: │
|
||||
│ │
|
||||
│ 1. Cookie session? │ → DB lookup session → get api_key → verify
|
||||
│ │
|
||||
│ 2. JWT Bearer? │ → verify JWT signature → decode claims
|
||||
│ │
|
||||
│ 3. X-API-Key? │ → SHA256 hash → DB lookup → verify
|
||||
│ │
|
||||
│ 4. ?api_key=? │ → same as #3
|
||||
│ │
|
||||
│ 5. None → 401 │
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Error Responses
|
||||
|
||||
| HTTP | When |
|
||||
|------|------|
|
||||
| `401` | Missing or invalid authentication |
|
||||
| `401` | Session expired or logged out |
|
||||
| `401` | JWT expired |
|
||||
| `401` | API key revoked or inactive |
|
||||
|
||||
---
|
||||
|
||||
### Related
|
||||
|
||||
- `POST /api/v1/resource/tmdb/check` — test authentication + TMDb API connectivity
|
||||
- `GET /health/detailed` — view auth status (integrations section)
|
||||
@@ -1,147 +0,0 @@
|
||||
<!-- module: health -->
|
||||
<!-- description: Health check endpoints -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
## Health Check
|
||||
|
||||
### `GET /health`
|
||||
|
||||
**Auth**: Public
|
||||
**Scope**: system-level
|
||||
|
||||
Returns basic server health status — used by load balancers and monitoring.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl "$API/health" | jq '{status, version}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"version": "1.0.0",
|
||||
"build_git_hash": "3a6c1865",
|
||||
"build_timestamp": "2026-05-16T13:38:15Z",
|
||||
"uptime_ms": 3015
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `status` | string | `ok` or `degraded` |
|
||||
| `version` | string | Semver version |
|
||||
| `build_git_hash` | string | Git commit hash |
|
||||
| `build_timestamp` | string | Binary build time |
|
||||
| `uptime_ms` | integer | Milliseconds since server start |
|
||||
|
||||
---
|
||||
|
||||
### `GET /health/detailed`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
Returns full system health including each service status, resource utilization, pipeline readiness, schema migration status, identity file sync status, and external integrations.
|
||||
|
||||
> Requires authentication (JWT, session cookie, or API key). The basic `/health` endpoint remains public for load balancer checks.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl "$API/health/detailed" | jq '{status, services, resources: {cpu: .resources.cpu_used_percent, memory: .resources.memory_used_percent}}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"version": "1.0.0",
|
||||
"services": {
|
||||
"postgres": {"status": "ok", "latency_ms": 3},
|
||||
"redis": {"status": "ok", "latency_ms": 1},
|
||||
"qdrant": {"status": "ok", "latency_ms": 5}
|
||||
},
|
||||
"resources": {
|
||||
"cpu_used_percent": 12.5,
|
||||
"memory_available_mb": 32768,
|
||||
"memory_used_percent": 31.7
|
||||
},
|
||||
"pipeline": {
|
||||
"scripts_ready": true,
|
||||
"scripts_count": 345,
|
||||
"processors": {
|
||||
"asr": true,
|
||||
"yolo": true,
|
||||
"face": true,
|
||||
"pose": true,
|
||||
"ocr": true,
|
||||
"cut": true,
|
||||
"scene": true,
|
||||
"asrx": true,
|
||||
"visual_chunk": true
|
||||
},
|
||||
"models_ready": true,
|
||||
"models_count": 42,
|
||||
"scripts_integrity": {"matched": 332, "total": 345, "ok": false},
|
||||
"ffmpeg": true
|
||||
},
|
||||
"schema": {
|
||||
"table_exists": true,
|
||||
"applied": [{"filename": "migrate_add_users_table.sql"}],
|
||||
"required": [],
|
||||
"ok": true
|
||||
},
|
||||
"identities": {
|
||||
"directory_exists": true,
|
||||
"files_count": 3481,
|
||||
"index_ok": true,
|
||||
"db_count": 3481,
|
||||
"synced": true
|
||||
},
|
||||
"integrations": {
|
||||
"tmdb": {
|
||||
"api_key_configured": false,
|
||||
"enabled": false,
|
||||
"api_reachable": null
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `status` | string | `ok` if all essential services healthy |
|
||||
| `services` | object | Per-service status (postgres, redis, qdrant) |
|
||||
| `services.*.status` | string | `ok`, `error`, or `degraded` |
|
||||
| `services.*.latency_ms` | int | Response time in milliseconds |
|
||||
| `resources` | object | CPU, memory usage |
|
||||
| `pipeline.scripts_ready` | boolean | Scripts directory accessible |
|
||||
| `pipeline.scripts_count` | int | Number of Python processor scripts |
|
||||
| `pipeline.processors` | object | Per-processor availability |
|
||||
| `pipeline.models_ready` | boolean | Models directory accessible |
|
||||
| `pipeline.scripts_integrity` | object | SHA256 checksum verification results |
|
||||
| `schema.ok` | boolean | All required migrations applied |
|
||||
| `identities.synced` | boolean | Identity file count matches DB count |
|
||||
| `integrations.tmdb` | object | TMDB API key config and reachability |
|
||||
|
||||
#### Health status rules
|
||||
|
||||
| Condition | status |
|
||||
|-----------|--------|
|
||||
| All services ok | `ok` |
|
||||
| Any service error | `degraded` |
|
||||
| Postgres or Redis error | `degraded` (server still responds) |
|
||||
|
||||
---
|
||||
|
||||
### Stats Endpoints
|
||||
|
||||
| Method | Endpoint | Auth | Description |
|
||||
|--------|----------|------|-------------|
|
||||
| GET | `/api/v1/stats/sftpgo` | No | SFTPGo service status |
|
||||
@@ -1,184 +0,0 @@
|
||||
<!-- module: register -->
|
||||
<!-- description: File registration — register, scan -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
## File Registration
|
||||
|
||||
### `POST /api/v1/files/register`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Register a video file for processing. Returns the file's metadata and UUID.
|
||||
|
||||
**New in v0.1.2**: Registration now **automatically triggers the processing pipeline** — no need to call `POST /api/v1/file/:file_uuid/process` separately. The system will:
|
||||
1. Register the file and run ffprobe
|
||||
2. Auto-run offline TMDb probe (reads local identity files, no API calls)
|
||||
3. Create a monitor job for the worker
|
||||
4. Worker starts all 10 processors (Cut → ASR → ASRX → YOLO → OCR → Face → Pose → VisualChunk → Story → 5W1H)
|
||||
|
||||
If the file already exists (same content hash), returns the existing record with `already_exists: true`.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `file_path` | string | Yes | — | Path to video file on disk |
|
||||
| `pattern` | string | No | — | Regex pattern for batch register (requires `file_path` to be a directory) |
|
||||
| `user_id` | integer | No | — | User ID to associate with registration |
|
||||
| `content_hash` | string | No | — | Pre-computed SHA-256 hash (skips computation) |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Register a single file
|
||||
curl -s -X POST "$API/api/v1/files/register" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"file_path": "/path/to/video.mp4"}'
|
||||
|
||||
# Batch register files matching a pattern in a directory
|
||||
curl -s -X POST "$API/api/v1/files/register" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"file_path": "/path/to/dir", "pattern": ".*\\.mp4$"}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"file_uuid": "3a6c1865...",
|
||||
"file_name": "video.mp4",
|
||||
"file_path": "/path/to/video.mp4",
|
||||
"file_type": "video",
|
||||
"duration": 120.5,
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"fps": 24.0,
|
||||
"total_frames": 2892,
|
||||
"already_exists": false,
|
||||
"message": "File registered successfully"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `success` | boolean | Always true on 200 |
|
||||
| `file_uuid` | string | 32-char hex UUID of the registered file |
|
||||
| `file_name` | string | File name (auto-renamed if name conflict) |
|
||||
| `file_path` | string | Canonical path on disk |
|
||||
| `file_type` | string | `"video"`, `"audio"`, or `"unknown"` |
|
||||
| `duration` | float | Duration in seconds |
|
||||
| `width` | integer | Video width in pixels |
|
||||
| `height` | integer | Video height in pixels |
|
||||
| `fps` | float | Frames per second |
|
||||
| `total_frames` | integer | Total frame count |
|
||||
| `already_exists` | boolean | True if same content was already registered |
|
||||
| `message` | string | Human-readable status |
|
||||
|
||||
#### Error Responses
|
||||
|
||||
| HTTP | When |
|
||||
|------|------|
|
||||
| `401` | Missing or invalid API key |
|
||||
| `400` | Invalid request body |
|
||||
| `404` | File path does not exist |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/files/scan`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Scan the filesystem directory and list all media files, showing which are registered, processing, or unregistered.
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `page` | integer | No | 1 | Page number (1-based) |
|
||||
| `page_size` | integer | No | all | Items per page (alias: `limit`) |
|
||||
| `limit` | integer | No | all | Max items (alias for `page_size`) |
|
||||
| `pattern` | string | No | — | Regex filter on file name (e.g., `.*\\.mp4$`) |
|
||||
| `sort_by` | string | No | `name` | Sort field: `name`, `size`, `modified`, `status` |
|
||||
| `sort_order` | string | No | `asc` | Sort direction: `asc` or `desc` |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Full scan
|
||||
curl -s "$API/api/v1/files/scan" -H "X-API-Key: $KEY" | jq '{total, registered_count, unregistered_count}'
|
||||
|
||||
# Paginated (page 1, 5 per page)
|
||||
curl -s "$API/api/v1/files/scan?page=1&page_size=5" -H "X-API-Key: $KEY" | jq '{page, total_pages, files: [.files[].file_name]}'
|
||||
|
||||
# Regex filter: only mp4 files
|
||||
curl -s "$API/api/v1/files/scan?pattern=.*\\.mp4$" -H "X-API-Key: $KEY" | jq '{filtered_total, files: [.files[].file_name]}'
|
||||
|
||||
# Sort by file size (largest first)
|
||||
curl -s "$API/api/v1/files/scan?sort_by=size&sort_order=desc&page_size=5" -H "X-API-Key: $KEY" | jq '[.files[] | {file_name, file_size}]'
|
||||
|
||||
# Sort by modified time (most recent first)
|
||||
curl -s "$API/api/v1/files/scan?sort_by=modified&sort_order=desc&page_size=5" -H "X-API-Key: $KEY" | jq '[.files[] | {file_name, modified_time}]'
|
||||
|
||||
# Sort by status
|
||||
curl -s "$API/api/v1/files/scan?sort_by=status&page_size=5" -H "X-API-Key: $KEY" | jq '[.files[] | {file_name, status}]'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"files": [
|
||||
{
|
||||
"file_name": "video.mp4",
|
||||
"file_size": 12345678,
|
||||
"is_registered": true,
|
||||
"file_uuid": "3a6c1865...",
|
||||
"status": "completed",
|
||||
"registration_time": "2026-05-16T12:00:00Z",
|
||||
"job_id": 42
|
||||
}
|
||||
],
|
||||
"total": 107,
|
||||
"filtered_total": 80,
|
||||
"page": 1,
|
||||
"page_size": 20,
|
||||
"total_pages": 4,
|
||||
"registered_count": 26,
|
||||
"unregistered_count": 81
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `files` | array | Array of file info objects (paginated) |
|
||||
| `files[].file_name` | string | File name |
|
||||
| `files[].relative_path` | string | Path relative to scan root |
|
||||
| `files[].file_path` | string | Absolute path on disk |
|
||||
| `files[].file_size` | integer | File size in bytes |
|
||||
| `files[].modified_time` | string | Last modified timestamp (ISO8601) |
|
||||
| `files[].is_registered` | boolean | Whether file is registered in DB |
|
||||
| `files[].file_uuid` | string | 32-char hex UUID (only if registered) |
|
||||
| `files[].status` | string | `"completed"`, `"processing"`, `"registered"`, `"unregistered"`, or `null` |
|
||||
| `files[].registration_time` | string | DB registration timestamp (only if registered) |
|
||||
| `files[].job_id` | integer | Processing job ID (only if a job exists) |
|
||||
| `total` | integer | Total files found on disk (unfiltered) |
|
||||
| `filtered_total` | integer | Files matching regex filter |
|
||||
| `page` | integer | Current page number |
|
||||
| `page_size` | integer | Items per page |
|
||||
| `total_pages` | integer | Total pages |
|
||||
| `registered_count` | integer | Files registered in DB |
|
||||
| `unregistered_count` | integer | Files not yet registered |
|
||||
|
||||
#### Notes
|
||||
|
||||
| Feature | Behavior |
|
||||
|---------|----------|
|
||||
| **Regex** | Case-insensitive (`(?i)` prefix auto-applied). Applied to `file_name`. |
|
||||
| **Sort order** | Default (`sort_by=name`): registered files first, then alphabetically. `sort_by=status`: alphabetical by status string. |
|
||||
| **Pagination** | `page_size` and `limit` are aliases. Default: show all results. |
|
||||
| **Processing order** | `pattern` regex filter → `sort_by`/`sort_order` → `page`/`page_size` slice. |
|
||||
@@ -1,138 +0,0 @@
|
||||
<!-- module: lookup -->
|
||||
<!-- description: File lookup by name and unregistration -->
|
||||
<!-- depends: 01_auth, 03_register -->
|
||||
|
||||
## File Lookup
|
||||
|
||||
### `GET /api/v1/files/lookup`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Search registered files by file name. Performs a case-insensitive LIKE search on the file name column. Returns basic info about matching files.
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `file_name` | string | Yes | File name to search for (partial matches supported) |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Look up a specific file
|
||||
curl -s "$API/api/v1/files/lookup?file_name=video.mp4" \
|
||||
-H "X-API-Key: $KEY"
|
||||
|
||||
# Partial name search
|
||||
curl -s "$API/api/v1/files/lookup?file_name=charade" \
|
||||
-H "X-API-Key: $KEY" | jq '.matches[].file_name'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"file_name": "video.mp4",
|
||||
"exists": true,
|
||||
"matches": [
|
||||
{
|
||||
"file_uuid": "a03485a40b2df2d3",
|
||||
"file_name": "video.mp4",
|
||||
"file_type": "video",
|
||||
"status": "completed"
|
||||
}
|
||||
],
|
||||
"next_name": "video (2).mp4"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `file_name` | string | Searched name |
|
||||
| `exists` | boolean | Exact name match exists |
|
||||
| `matches` | array | Array of matching registered files |
|
||||
| `matches[].file_uuid` | string | 32-char hex UUID |
|
||||
| `matches[].file_name` | string | Registered file name |
|
||||
| `matches[].file_type` | string | `"video"`, `"audio"`, or `null` |
|
||||
| `matches[].status` | string | Registration/processing status |
|
||||
| `next_name` | string | Suggested name for avoiding conflicts |
|
||||
|
||||
---
|
||||
|
||||
## Unregister
|
||||
|
||||
### `POST /api/v1/unregister`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Delete a registered file from the system. Supports single file by UUID, or batch by directory + regex pattern.
|
||||
|
||||
#### What gets deleted
|
||||
|
||||
| Removed (default) | Not removed |
|
||||
|---------|-------------|
|
||||
| Database records (videos, chunks, embeddings, processor_results, pre_chunks) | The original source video file on disk |
|
||||
| Processor output JSON files (`{uuid}.*.json`) — unless `delete_output_files: false` | Temp/working directories |
|
||||
| In-memory cache entries | |
|
||||
| MongoDB cached lists | |
|
||||
|
||||
> ⚠️ Database deletion is **irreversible**. To keep output files, set `"delete_output_files": false`.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
At least one mode must be specified: either `file_uuid` alone, or `file_path` + `pattern` together.
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `file_uuid` | string | * | — | Single file UUID to delete |
|
||||
| `file_path` | string | * | — | Directory path (for batch delete) |
|
||||
| `pattern` | string | * | — | Regex pattern (requires `file_path`) |
|
||||
| `delete_output_files` | boolean | No | `true` | If `true`, also delete processor output JSON files (`{uuid}.*.json`). Set to `false` to keep them. |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Delete a single file by UUID (default: also deletes output JSON files)
|
||||
curl -s -X POST "$API/api/v1/unregister" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"file_uuid": "'"$FILE_UUID"'"}'
|
||||
|
||||
# Keep output JSON files, only delete DB records
|
||||
curl -s -X POST "$API/api/v1/unregister" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"file_uuid": "'"$FILE_UUID"'", "delete_output_files": false}'
|
||||
|
||||
# Batch delete all mp4 files in a directory
|
||||
curl -s -X POST "$API/api/v1/unregister" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"file_path": "/path/to/dir", "pattern": ".*\\.mp4$"}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"file_uuid": "a03485a40b2df2d3",
|
||||
"message": "Video unregistered successfully"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `success` | boolean | True if deletion succeeded |
|
||||
| `file_uuid` | string | UUID of the deleted file (single mode) |
|
||||
| `message` | string | Human-readable status |
|
||||
|
||||
#### Error Responses
|
||||
|
||||
| HTTP | When |
|
||||
|------|------|
|
||||
| `400` | Neither `file_uuid` nor `file_path`+`pattern` provided |
|
||||
| `404` | File UUID not found |
|
||||
| `401` | Missing or invalid API key |
|
||||
@@ -1,236 +0,0 @@
|
||||
<!-- module: process -->
|
||||
<!-- description: Processing pipeline — trigger, probe, progress, jobs -->
|
||||
<!-- depends: 01_auth, 03_register -->
|
||||
|
||||
## Processing Pipeline
|
||||
|
||||
### `POST /api/v1/file/:file_uuid/process`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Trigger the processing pipeline for a registered file. Creates a monitor job that the worker picks up and processes sequentially. Returns immediately with the job info—processing runs asynchronously in the background.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `processors` | string[] | No | all | Specific processors to run: `["cut","asr","asrx","yolo","ocr","face","pose","visual_chunk","story","5w1h"]` |
|
||||
| `rules` | string[] | No | all | Rule names to apply (currently unused) |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Run all processors
|
||||
curl -s -X POST "$API/api/v1/file/$FILE_UUID/process" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" -d '{}'
|
||||
|
||||
# Run specific processors only
|
||||
curl -s -X POST "$API/api/v1/file/$FILE_UUID/process" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"processors": ["asr", "face", "yolo"]}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"job_id": 42,
|
||||
"file_uuid": "3a6c1865...",
|
||||
"status": "processing",
|
||||
"pids": [12345, 12346],
|
||||
"message": "Processing triggered for video.mp4"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `success` | boolean | Always true on 200 |
|
||||
| `job_id` | integer | Monitor job ID (for job tracking) |
|
||||
| `file_uuid` | string | 32-char hex UUID of the file |
|
||||
| `status` | string | `"processing"` |
|
||||
| `pids` | integer[] | Process IDs of started processors |
|
||||
| `message` | string | Human-readable status |
|
||||
|
||||
#### Error Responses
|
||||
|
||||
| HTTP | When |
|
||||
|------|------|
|
||||
| `404` | File UUID not found |
|
||||
| `401` | Missing or invalid API key |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/probe`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Get ffprobe metadata for a registered file. Returns video/audio stream info, codec details, duration, resolution, and frame rate.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/file/$FILE_UUID/probe" -H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"file_uuid": "3a6c1865...",
|
||||
"file_name": "video.mp4",
|
||||
"file_size": 794863677,
|
||||
"duration": 120.5,
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"fps": 24.0,
|
||||
"total_frames": 2892,
|
||||
"cached": true,
|
||||
"format": {
|
||||
"filename": "/path/to/video.mp4",
|
||||
"format_name": "mov,mp4,m4a,3gp",
|
||||
"duration": "120.5",
|
||||
"size": "12345678",
|
||||
"bit_rate": "819200"
|
||||
},
|
||||
"streams": [
|
||||
{
|
||||
"index": 0,
|
||||
"codec_name": "h264",
|
||||
"codec_type": "video",
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"r_frame_rate": "24/1",
|
||||
"duration": "120.5"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `file_uuid` | string | 32-char hex UUID |
|
||||
| `file_name` | string | File name |
|
||||
| `file_size` | integer | File size in bytes (from filesystem) |
|
||||
| `duration` | float | Duration in seconds |
|
||||
| `width` | integer | Video width in pixels |
|
||||
| `height` | integer | Video height in pixels |
|
||||
| `fps` | float | Frames per second |
|
||||
| `total_frames` | integer | Estimated total frames |
|
||||
| `cached` | boolean | True if result was from cached probe JSON |
|
||||
| `format` | object | Container format info (ffprobe format section) |
|
||||
| `streams` | array | Array of stream info objects |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/progress/:file_uuid`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Get real-time processing progress for a file via Redis pub/sub. Includes per-processor status, current/total frames, ETA, and system resource stats.
|
||||
|
||||
#### Pipeline Order
|
||||
|
||||
| Order | Processor | Dependencies | Description |
|
||||
|-------|-----------|-------------|-------------|
|
||||
| 1 | `cut` | — | Scene detection |
|
||||
| 2 | `asr` | cut | Speech-to-text (per scene) |
|
||||
| 3 | `asrx` | asr | Speaker diarization |
|
||||
| 4 | `yolo` | — | Object detection |
|
||||
| 5 | `ocr` | — | Text recognition |
|
||||
| 6 | `face` | — | Face detection & embedding |
|
||||
| 7 | `pose` | — | Pose estimation |
|
||||
| 8 | `visual_chunk` | yolo | Visual scene chunks |
|
||||
| 9 | `story` | asr, asrx, cut, yolo, face | Scene summaries (template) |
|
||||
| 10 | `5w1h` | story | 5W1H analysis (Gemma4 LLM) |
|
||||
|
||||
All processors except `story` and `5w1h` run concurrently when their dependencies are met. Story and 5W1H run sequentially after their prerequisites.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/progress/$FILE_UUID" -H "X-API-Key: $KEY" | jq '{overall_progress, processors: [.processors[] | {processor_type, status}]}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"file_uuid": "3a6c1865...",
|
||||
"overall_progress": 71,
|
||||
"cpu_percent": 45.2,
|
||||
"gpu_percent": 30.1,
|
||||
"memory_percent": 62.4,
|
||||
"processors": [
|
||||
{"processor_type": "asr", "status": "complete", "progress": 100},
|
||||
{"processor_type": "yolo", "status": "running", "progress": 65},
|
||||
{"processor_type": "face", "status": "pending", "progress": 0}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `file_uuid` | string | 32-char hex UUID |
|
||||
| `overall_progress` | integer | Overall progress percentage (0–100) |
|
||||
| `processors` | array | Per-processor status list |
|
||||
| `processors[].processor_type` | string | Processor name (`asr`, `cut`, `yolo`, etc.) |
|
||||
| `processors[].status` | string | `"pending"`, `"running"`, `"complete"`, or `"failed"` |
|
||||
| `processors[].progress` | integer | Per-processor progress (0–100) |
|
||||
| `processors[].eta_seconds` | integer | Estimated seconds remaining (running processors) |
|
||||
| `processors[].current` | integer | Current frame count |
|
||||
| `processors[].total` | integer | Total frame count |
|
||||
| `cpu_percent` | float | Current CPU usage |
|
||||
| `gpu_percent` | float | Current GPU utilization |
|
||||
| `memory_percent` | float | Current memory usage |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/jobs`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
List all processing jobs (monitor jobs) in the system. Shows job status, which file each job is processing, and current processor info.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/jobs" -H "X-API-Key: $KEY" | jq '{count, jobs: [.jobs[] | {uuid, status}]}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"jobs": [
|
||||
{
|
||||
"id": 42,
|
||||
"uuid": "3a6c1865...",
|
||||
"status": "running",
|
||||
"current_processor": "yolo",
|
||||
"created_at": "2026-05-16T12:00:00Z",
|
||||
"started_at": "2026-05-16T12:01:00Z"
|
||||
}
|
||||
],
|
||||
"count": 15,
|
||||
"page": 1,
|
||||
"page_size": 20
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `jobs` | array | Array of job info objects |
|
||||
| `jobs[].id` | integer | Job ID |
|
||||
| `jobs[].uuid` | string | File UUID being processed |
|
||||
| `jobs[].status` | string | `"pending"`, `"running"`, `"completed"`, `"failed"` |
|
||||
| `jobs[].current_processor` | string | Currently active processor, or null |
|
||||
| `count` | integer | Total job count |
|
||||
| `page` | integer | Current page number |
|
||||
| `page_size` | integer | Jobs per page |
|
||||
@@ -1,145 +0,0 @@
|
||||
<!-- module: search -->
|
||||
<!-- description: Vector search, BM25, smart search, universal search, visual search -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
## Search APIs
|
||||
|
||||
### `POST /api/v1/search/smart`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Semantic vector search using EmbeddingGemma-300m. Generates a query embedding via EmbeddingGemma (port 11436), then searches pgvector `story_parent` and `llm_parent` chunks by cosine similarity.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `file_uuid` | string | Yes | — | File UUID to search within |
|
||||
| `query` | string | Yes | — | Search text |
|
||||
| `limit` | integer | No | 5 | Max results to return |
|
||||
| `page` | integer | No | 1 | Page number |
|
||||
| `page_size` | integer | No | 5 | Items per page |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/search/smart" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $JWT" \
|
||||
-d '{"file_uuid": "'"$FILE_UUID"'", "query": "Audrey Hepburn"}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "Audrey Hepburn",
|
||||
"results": [
|
||||
{
|
||||
"parent_id": 1087822,
|
||||
"scene_order": 1087822,
|
||||
"start_frame": 104438,
|
||||
"end_frame": 104538,
|
||||
"fps": 24.0,
|
||||
"start_time": 4351.6,
|
||||
"end_time": 4355.76,
|
||||
"summary": "[4352s-4356s, 4s] Cast: Audrey Hepburn. Total: 2 lines, 10 words. Speakers: Audrey Hepburn (2 lines)",
|
||||
"similarity": 0.67
|
||||
}
|
||||
],
|
||||
"page": 1,
|
||||
"page_size": 5,
|
||||
"strategy": "semantic_vector_search"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/search/universal`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Multi-type BM25 full-text search across chunks, frames, and persons. Uses PostgreSQL `tsvector`.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `query` | string | Yes | — | Search text |
|
||||
| `file_uuid` | string | No | — | Restrict to specific file |
|
||||
| `types` | string[] | No | `["chunk","frame","person"]` | Search types |
|
||||
| `limit` | integer | No | 10 | Max results per type |
|
||||
| `page` | integer | No | 1 | Page number |
|
||||
| `page_size` | integer | No | 20 | Items per page |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/search/universal" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $JWT" \
|
||||
-d '{"file_uuid": "'"$FILE_UUID"'", "query": "Cary Grant"}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"type": "chunk",
|
||||
"chunk_id": "bd80fec92b0b6963d177a2c55bf713e2_2",
|
||||
"chunk_type": "story_child",
|
||||
"start_frame": 5103,
|
||||
"end_frame": 5127,
|
||||
"start_time": 212.64,
|
||||
"end_time": 213.64,
|
||||
"text": "[213s-214s] Cary Grant: \"Olá!\"",
|
||||
"score": 0.9
|
||||
}
|
||||
],
|
||||
"total": 20,
|
||||
"took_ms": 18
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/search/frames`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Search face detection frames by identity name or trace ID.
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/search/identity_text`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Search text chunks spoken by a specific identity.
|
||||
|
||||
---
|
||||
|
||||
### Visual Search
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| POST | `/api/v1/search/visual` | Search visual chunks |
|
||||
| POST | `/api/v1/search/visual/class` | Search by object class |
|
||||
| POST | `/api/v1/search/visual/density` | Search by object density |
|
||||
| POST | `/api/v1/search/visual/combination` | Search by object combination |
|
||||
| POST | `/api/v1/search/visual/stats` | Visual chunk statistics |
|
||||
|
||||
#### Embedding Model
|
||||
|
||||
| Detail | Value |
|
||||
|--------|-------|
|
||||
| **Model** | EmbeddingGemma-300m |
|
||||
| **Endpoint** | `POST /api/v1/embeddings` on port 11436 |
|
||||
| **Dimension** | 768 |
|
||||
| **Storage** | pgvector (`chunk.embedding` column) |
|
||||
@@ -1,516 +0,0 @@
|
||||
<!-- module: identity -->
|
||||
<!-- description: Global identities — CRUD, detail, files, faces, bind, unbind, search -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
## Global Identities
|
||||
|
||||
### `GET /api/v1/identities`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
List all registered identities with pagination.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identities?page=1&page_size=20" -H "X-API-Key: $KEY" | jq '{count, identities: [.identities[] | {name}]}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/identity/:identity_uuid`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Get detailed information for a specific identity, including metadata and TMDb references.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identity/$IDENTITY_UUID" -H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
|
||||
"name": "Cary Grant",
|
||||
"identity_type": "people",
|
||||
"source": "tmdb",
|
||||
"status": "confirmed",
|
||||
"tmdb_id": 112,
|
||||
"tmdb_profile": "{output}/identities/{identity_uuid}/profile.jpg",
|
||||
"metadata": {},
|
||||
"reference_data": {},
|
||||
"created_at": "2026-05-16T12:00:00Z",
|
||||
"updated_at": null
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `identity_uuid` | string | Identity identifier |
|
||||
| `name` | string | Identity name |
|
||||
| `identity_type` | string | `"people"` or null |
|
||||
| `source` | string | `.json`, `auto`, `tmdb`, `user_defined`, or `merged` |
|
||||
| `status` | string | `"confirmed"`, `"pending"`, or `"inactive"` |
|
||||
| `tmdb_id` | integer | TMDb person ID (only if source = tmdb) |
|
||||
| `tmdb_profile` | string | Local profile image path (`{output}/identities/{uuid}/profile.jpg`) |
|
||||
| `metadata` | object | Metadata JSON (tmdb_character, cast_order, etc.) |
|
||||
| `created_at` | string | Creation timestamp |
|
||||
|
||||
---
|
||||
|
||||
### `DELETE /api/v1/identity/:identity_uuid`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Delete an identity permanently.
|
||||
|
||||
---
|
||||
|
||||
### `PATCH /api/v1/identity/:identity_uuid`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Partially update an identity. Only provided fields are modified. The `name` field is a display label and may repeat across identities. Aliases for multilingual display are stored in `metadata.aliases` (see BCP 47 reference below).
|
||||
|
||||
#### Request (JSON, all fields optional)
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `name` | string | New display name |
|
||||
| `metadata` | object | Merged into existing metadata. Use `"aliases"` key for locale-tagged names |
|
||||
| `status` | string | `"confirmed"`, `"pending"`, or `"skipped"` |
|
||||
| `identity_type` | string | `"people"`, `"brand"`, `"object"`, `"concept"`, etc. |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH "$API/api/v1/identity/$IDENTITY_UUID" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "John Smith",
|
||||
"metadata": {
|
||||
"aliases": [
|
||||
{"locale": "en", "name": "John Smith"},
|
||||
{"locale": "zh-TW", "name": "約翰·史密斯"},
|
||||
{"locale": "ja", "name": "ジョン・スミス"}
|
||||
]
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
|
||||
"updated_fields": ["name", "metadata"]
|
||||
}
|
||||
```
|
||||
|
||||
#### Error Responses
|
||||
|
||||
| HTTP | When |
|
||||
|------|------|
|
||||
| `400` | No fields to update or invalid UUID format |
|
||||
| `404` | Identity not found |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/identity/:identity_uuid/files`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Get all files where this identity appears. Returns per-file summary including face count, confidence, and appearance time range.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identity/$IDENTITY_UUID/files" -H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "c3545906c82d4b66aa1d150bc02decce",
|
||||
"total": 1,
|
||||
"page": 1,
|
||||
"page_size": 20,
|
||||
"data": [
|
||||
{
|
||||
"file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
|
||||
"file_name": "Charade (1963) Cary Grant & Audrey Hepburn.mp4",
|
||||
"file_path": "/path/to/videos/Charade.mp4",
|
||||
"status": "completed",
|
||||
"face_count": 19695,
|
||||
"speaker_count": 0,
|
||||
"first_appearance": 206.76,
|
||||
"last_appearance": 6756.68,
|
||||
"confidence": 0.803
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `file_uuid` | string | File identifier (full 32-char hex) |
|
||||
| `file_name` | string | Video file name |
|
||||
| `file_path` | string | Absolute path to video file |
|
||||
| `status` | string | Video processing status (`"completed"`, `"processing"`, etc.) |
|
||||
| `face_count` | int | Total face detections for this identity in this file |
|
||||
| `speaker_count` | int | Speaker segments (reserved, always `0`) |
|
||||
| `first_appearance` | float | First appearance time in seconds (computed from `frame_number / fps`) |
|
||||
| `last_appearance` | float | Last appearance time in seconds |
|
||||
| `confidence` | float | Average detection confidence |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/identity/:identity_uuid/faces`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Get all face detection records associated with this identity.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identity/$IDENTITY_UUID/faces?page=1&page_size=20" -H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "c3545906c82d4b66aa1d150bc02decce",
|
||||
"total": 19695,
|
||||
"page": 1,
|
||||
"page_size": 20,
|
||||
"data": [
|
||||
{
|
||||
"id": 655704,
|
||||
"file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
|
||||
"frame_number": 5169,
|
||||
"timestamp_secs": 206.76,
|
||||
"face_id": "5169_0",
|
||||
"bbox": {
|
||||
"x": 706,
|
||||
"y": 469,
|
||||
"width": 618,
|
||||
"height": 618
|
||||
},
|
||||
"confidence": 0.855
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | int64 | Face detection record ID |
|
||||
| `file_uuid` | string | File where face was detected |
|
||||
| `frame_number` | int64 | Frame number (primary coordinate) |
|
||||
| `timestamp_secs` | float | Time in seconds (computed as `frame_number / fps`) |
|
||||
| `face_id` | string | Face ID (format: `{frame_number}_{detection_index}`) |
|
||||
| `bbox` | object | Bounding box |
|
||||
| `bbox.x` | float | Left coordinate |
|
||||
| `bbox.y` | float | Top coordinate |
|
||||
| `bbox.width` | float | Width in pixels |
|
||||
| `bbox.height` | float | Height in pixels |
|
||||
| `confidence` | float | Detection confidence (0.0–1.0) |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/identity/:identity_uuid/chunks`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Get all text chunks (sentences) spoken while this identity's face was on screen. Useful for finding what a person said.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identity/$IDENTITY_UUID/chunks" -H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
|
||||
"data": [
|
||||
{
|
||||
"id": 0,
|
||||
"file_uuid": "bd80fec92b0b6963d177a2c55bf713e2",
|
||||
"chunk_id": "bd80fec92b0b6963d177a2c55bf713e2_2",
|
||||
"chunk_type": "sentence",
|
||||
"start_frame": 5103,
|
||||
"end_frame": 5127,
|
||||
"fps": 24.0,
|
||||
"start_time": 212.64,
|
||||
"end_time": 213.64,
|
||||
"text_content": "[213s-214s] Cary Grant: \"Olá!\""
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `file_uuid` | string | File identifier |
|
||||
| `chunk_id` | string | Sentence chunk identifier |
|
||||
| `start_frame` | integer | Frame-accurate start position |
|
||||
| `end_frame` | integer | Frame-accurate end position |
|
||||
| `fps` | float | Frames per second |
|
||||
| `start_time` | float | Start time in seconds |
|
||||
| `end_time` | float | End time in seconds |
|
||||
| `text_content` | string | Spoken text content |
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/identity/:identity_uuid/bind`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Bind a face detection to an identity. Associates the face trace with the identity for future search and recognition.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `file_uuid` | string | Yes | File where face is detected |
|
||||
| `face_id` | string | Yes | Face ID (format: `{frame}_{idx}`) |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/identity/$IDENTITY_UUID/bind" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"file_uuid": "'"$FILE_UUID"'", "face_id": "1_5"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/identity/:identity_uuid/unbind`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Unbind a face detection from an identity. Removes the identity association from the face record.
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/identities/search`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Search identities by name (ILIKE search). Returns matching identity records.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identities/search?q=Cary" -H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `name` | string | Identity name |
|
||||
| `source` | string | Identity source |
|
||||
| `tmdb_id` | integer | TMDb ID (if source = tmdb) |
|
||||
| `file_uuid` | string | Associated file |
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/identity/upload`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Upload an identity.json file to create or update an identity. Accepts the same format as the identity.json files stored on disk.
|
||||
|
||||
If an identity with the same `identity_uuid` already exists, it will be updated with the new values.
|
||||
|
||||
#### Request
|
||||
|
||||
The request body is an `IdentityFile` object:
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `identity_uuid` | string | Yes | Identity identifier |
|
||||
| `name` | string | Yes | Identity display name |
|
||||
| `identity_type` | string | No | `"people"` or null |
|
||||
| `source` | string | No | `.json`, `auto`, `tmdb`, `user_defined`, or `merged` |
|
||||
| `status` | string | No | `"confirmed"`, `"pending"`, or `"inactive"` |
|
||||
| `tmdb_id` | integer | No | TMDb person ID |
|
||||
| `tmdb_profile` | string | No | TMDb profile image URL |
|
||||
| `metadata` | object | No | Arbitrary metadata JSON |
|
||||
| `file_bindings` | array | No | Array of `{ file_uuid, trace_ids, face_count }` (informational) |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/identity/upload" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"version": 1,
|
||||
"identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
|
||||
"name": "Cary Grant",
|
||||
"identity_type": "people",
|
||||
"source": ".json",
|
||||
"status": "confirmed",
|
||||
"metadata": {},
|
||||
"file_bindings": []
|
||||
}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
|
||||
"name": "Cary Grant",
|
||||
"message": "Identity uploaded successfully"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/identity/:identity_uuid/profile-image`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Upload a profile image (JPEG or PNG) for an identity. The image is saved to `{output}/identities/{uuid}/profile.{ext}`.
|
||||
|
||||
Uses `multipart/form-data` with field name `image`.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/identity/$IDENTITY_UUID/profile-image" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-F "image=@/path/to/photo.jpg"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
|
||||
"path": "/path/to/output/identities/.../profile.jpg",
|
||||
"message": "Profile image saved: profile.jpg"
|
||||
}
|
||||
```
|
||||
|
||||
#### Error Responses
|
||||
|
||||
| HTTP | When |
|
||||
|------|------|
|
||||
| `400` | Missing image field or unsupported format |
|
||||
| `404` | Identity not found |
|
||||
| `415` | Unsupported image type (use JPEG or PNG) |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/identity/:identity_uuid/profile-image`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: identity-level
|
||||
|
||||
Retrieve the profile image for an identity. Returns the raw image data with appropriate Content-Type header.
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/identity/$IDENTITY_UUID/profile-image" \
|
||||
-H "X-API-Key: $KEY" -o profile.jpg
|
||||
```
|
||||
|
||||
| Response Header | Value |
|
||||
|----------------|-------|
|
||||
| `content-type` | `image/jpeg` or `image/png` |
|
||||
|
||||
---
|
||||
|
||||
## Alias System (BCP 47 Locale Tags)
|
||||
|
||||
Identity aliases support multilingual display names. Aliases are stored in `metadata.aliases` as an array of `{locale, name}` objects.
|
||||
|
||||
### BCP 47 Locale Tags Reference
|
||||
|
||||
| Locale | Tag | Example |
|
||||
|--------|-----|---------|
|
||||
| English | `en` | John Smith |
|
||||
| Traditional Chinese | `zh-TW` | 約翰·史密斯 |
|
||||
| Simplified Chinese | `zh-CN` | 约翰·史密斯 |
|
||||
| Japanese | `ja` | ジョン・スミス |
|
||||
| Korean | `ko` | 존 스미스 |
|
||||
| Cantonese | `yue` | 約翰·史密夫 |
|
||||
| French | `fr` | John Smith (French spelling) |
|
||||
| Spanish | `es` | Juan Smith |
|
||||
| Arabic | `ar` | جون سميث |
|
||||
| Russian | `ru` | Джон Смит |
|
||||
| Thai | `th` | จอห์น สมิธ |
|
||||
|
||||
BCP 47 is the IETF standard for language tags. Format: `language` (e.g. `en`, `ja`) or `language-Region` (e.g. `zh-TW`, `zh-CN`).
|
||||
|
||||
### Frontend Display Logic
|
||||
|
||||
```javascript
|
||||
function getDisplayName(identity, preferredLocale) {
|
||||
const match = identity.metadata?.aliases?.find(a => a.locale === preferredLocale);
|
||||
if (match) return match.name;
|
||||
const lang = preferredLocale.split('-')[0];
|
||||
const langMatch = identity.metadata?.aliases?.find(a => a.locale.startsWith(lang));
|
||||
if (langMatch) return langMatch.name;
|
||||
return identity.name;
|
||||
}
|
||||
```
|
||||
|
||||
### Updating Aliases via PATCH
|
||||
|
||||
```json
|
||||
PATCH /api/v1/identity/:identity_uuid
|
||||
{
|
||||
"metadata": {
|
||||
"aliases": [
|
||||
{"locale": "en", "name": "John Smith"},
|
||||
{"locale": "zh-TW", "name": "約翰·史密斯"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
*Updated: 2026-05-22*
|
||||
|
||||
|
||||
@@ -1,65 +0,0 @@
|
||||
<!-- module: identity_agent -->
|
||||
<!-- description: Identity agent — match from photo, match from trace -->
|
||||
<!-- depends: 01_auth, 07_identity -->
|
||||
|
||||
## Identity Agent
|
||||
|
||||
### `POST /api/v1/agents/identity/match-from-photo`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Upload a face photo to match against known identities. Detects face via InsightFace, extracts 512D embedding via CoreML FaceNet, then searches pgvector for the closest identity.
|
||||
|
||||
#### Request
|
||||
|
||||
`multipart/form-data` with field `image` (JPEG/PNG) and optional `file_uuid`.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/agents/identity/match-from-photo" \
|
||||
-H "Authorization: Bearer $JWT" \
|
||||
-F "image=@/path/to/face.jpg" \
|
||||
-F "file_uuid=$FILE_UUID"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"matches": [
|
||||
{
|
||||
"identity_uuid": "a9a90105...",
|
||||
"name": "Cary Grant",
|
||||
"similarity": 0.87
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/agents/identity/match-from-trace`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Match a face trace (tracked face across frames) against known identities. Samples 3 angles from the trace, generates embeddings, and searches pgvector.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `file_uuid` | string | Yes | File containing the trace |
|
||||
| `trace_id` | integer | Yes | Face trace ID to match |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/agents/identity/match-from-trace" \
|
||||
-H "Authorization: Bearer $JWT" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"file_uuid": "'"$FILE_UUID"'", "trace_id": 10}'
|
||||
```
|
||||
@@ -1,317 +0,0 @@
|
||||
<!-- module: media -->
|
||||
<!-- description: Video streaming & frame extraction -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
## Video Streaming & Frame Extraction
|
||||
|
||||
All video streaming endpoints support the following common query parameters:
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `mode` | string | No | `normal` | `normal` or `debug` (draws detection overlays) |
|
||||
| `audio` | string | No | `on` | `on` or `off` |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/video`
|
||||
|
||||
Stream the full video file with range support for seeking.
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
#### Response
|
||||
|
||||
- **200**: Video stream (`Content-Type` based on file extension)
|
||||
- **206**: Partial content (range request)
|
||||
- Supports `Range` header for seeking
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/trace/:trace_id/video`
|
||||
|
||||
Stream video with highlights for a specific face trace (follows a single person across frames with bounding box overlay).
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/trace/:trace_id/representative-face`
|
||||
|
||||
Find the best single face to represent this trace. Uses a two-stage selection: SQL (area × confidence → top 10) then FFmpeg `blurdetect` (sharpness → pick the least blurry).
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/file/$FILE_UUID/trace/1939/representative-face" \
|
||||
-H "X-API-Key: $KEY"
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
|
||||
"trace_id": 1939,
|
||||
"face_count": 538,
|
||||
"representative": {
|
||||
"frame_number": 68193,
|
||||
"timestamp_secs": 2727.72,
|
||||
"bbox": { "x": 347, "y": 378, "width": 427, "height": 427 },
|
||||
"confidence": 0.760,
|
||||
"quality_score": 138516,
|
||||
"blur_score": 9.46
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `trace_id` | integer | Face trace ID |
|
||||
| `face_count` | integer | Total face detections in this trace |
|
||||
| `representative.frame_number` | integer | Frame number of the selected face (primary coordinate) |
|
||||
| `representative.timestamp_secs` | float | Time in seconds (derived from `frame_number / fps`) |
|
||||
| `representative.bbox` | object | Bounding box `{x, y, width, height}` |
|
||||
| `representative.confidence` | float | Detection confidence (0.0–1.0) |
|
||||
| `representative.quality_score` | float | Pre-selection score (`area × confidence`) |
|
||||
| `representative.blur_score` | float | FFmpeg blurdetect result (lower = sharper) |
|
||||
|
||||
#### Error Responses
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/trace/:trace_id/thumbnail`
|
||||
|
||||
Extract the best face image for a trace as JPEG (320×320). Internally selects the face using the same two-stage algorithm as `representative-face`, then crops via FFmpeg. The result is cacheable for 24 hours.
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/file/$FILE_UUID/trace/1939/thumbnail" \
|
||||
-H "X-API-Key: $KEY" -o trace_1939_face.jpg
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
- **200**: `image/jpeg` binary data (320×320 cropped face)
|
||||
- **404**: File, trace not found, or no suitable face
|
||||
- **500**: FFmpeg or database error
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/identities/:identity_uuid_a/co-occur-with/:identity_uuid_b`
|
||||
|
||||
Find the first frame where two identities appear together, with representative face thumbnails for both.
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Audrey Hepburn & Cary Grant 第一次同框
|
||||
curl -s "$API/api/v1/file/$FILE_UUID/identities/$AUDREY_UUID/co-occur-with/$CARY_UUID" \
|
||||
-H "X-API-Key: $KEY" | jq '{identity_a: .identity_a.name, identity_b: .identity_b.name, first_frame: .first_cooccurrence.frame_number}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
|
||||
"identity_a": {
|
||||
"identity_uuid": "c3545906-c82d-4b66-aa1d-150bc02decce",
|
||||
"name": "Audrey Hepburn",
|
||||
"trace_id": 920
|
||||
},
|
||||
"identity_b": {
|
||||
"identity_uuid": "2b0ddefe-e2a9-4533-9308-b375594604d5",
|
||||
"name": "Cary Grant",
|
||||
"trace_id": 919
|
||||
},
|
||||
"first_cooccurrence": {
|
||||
"frame_number": 38165,
|
||||
"timestamp_secs": 1526.60,
|
||||
"total_cooccurrence_frames": 3136,
|
||||
"representative_face_a": {
|
||||
"frame_number": 38199,
|
||||
"bbox": { "x": 122, "y": 339, "width": 176, "height": 176 },
|
||||
"confidence": 0.832,
|
||||
"thumbnail_url": "/api/v1/file/aeed71342.../trace/920/thumbnail"
|
||||
},
|
||||
"representative_face_b": {
|
||||
"frame_number": 38291,
|
||||
"bbox": { "x": 511, "y": 315, "width": 192, "height": 192 },
|
||||
"confidence": 0.791,
|
||||
"thumbnail_url": "/api/v1/file/aeed71342.../trace/919/thumbnail"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `identity_a.name` | string | First identity name |
|
||||
| `identity_b.name` | string | Second identity name |
|
||||
| `first_cooccurrence.frame_number` | int | First frame where both appear |
|
||||
| `first_cooccurrence.timestamp_secs` | float | Time in seconds |
|
||||
| `first_cooccurrence.total_cooccurrence_frames` | int | Total frames with both present |
|
||||
| `first_cooccurrence.representative_face_a/b` | object | Best face thumbnail data for each identity |
|
||||
|
||||
#### Error Responses
|
||||
|
||||
| HTTP | When |
|
||||
|------|------|
|
||||
| `404` | File or identity not found |
|
||||
| `404` | The two identities never co-occur in this file |
|
||||
| `500` | Database or FFmpeg error |
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/video/bbox`
|
||||
|
||||
Stream video with bounding box overlay for all detected objects/faces.
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Uses a built-in 5×7 bitmap font renderer to draw labels directly on video frames via FFmpeg `drawtext` filter.
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/thumbnail`
|
||||
|
||||
Extract a single frame from a video as JPEG image. Uses FFmpeg `select` filter.
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `frame` | integer | Yes | — | Zero-based frame number to extract |
|
||||
| `x` | integer | No | — | Crop start X (left edge). Requires `y`, `w`, `h`. |
|
||||
| `y` | integer | No | — | Crop start Y (top edge). Requires `x`, `w`, `h`. |
|
||||
| `w` | integer | No | — | Crop width in pixels. Requires `x`, `y`, `h`. |
|
||||
| `h` | integer | No | — | Crop height in pixels. Requires `x`, `y`, `w`. |
|
||||
|
||||
All four crop params (`x`, `y`, `w`, `h`) must be provided together or omitted.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Extract frame 1000 (full frame)
|
||||
curl -s "$API/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/thumbnail?frame=1000" \
|
||||
-H "Authorization: Bearer $JWT" -o frame_1000.jpg
|
||||
|
||||
# Extract and crop face region (x=320, y=240, w=160, h=160)
|
||||
curl -s "$API/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/thumbnail?frame=1000&x=320&y=240&w=160&h=160" \
|
||||
-H "Authorization: Bearer $JWT" -o face_crop.jpg
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
- **200**: `image/jpeg` binary data
|
||||
- **404**: File not found
|
||||
- **500**: FFmpeg error (e.g., frame number exceeds video duration)
|
||||
|
||||
### `GET /api/v1/file/:file_uuid/clip`
|
||||
|
||||
Extract a video clip (time range) as MPEG-TS stream. Uses FFmpeg `-ss` fast seek.
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `start_frame` | integer | No* | — | Start frame (zero-based). **Frame-accurate** — use this for precision. |
|
||||
| `end_frame` | integer | No* | — | End frame (zero-based, inclusive). Requires `start_frame`. |
|
||||
| `start_time` | float | No* | — | Start time in seconds. Approximate (FPS-dependent). Fallback if frames not given. |
|
||||
| `end_time` | float | No* | — | End time in seconds. Approximate (FPS-dependent). Fallback if frames not given. |
|
||||
| `fps` | float | No | video FPS | Override frames-per-second for frame↔time calculation. Defaults to video's detected FPS. |
|
||||
| `mode` | string | No | `normal` | `normal` or `debug` (draws "CLIP" overlay) |
|
||||
| `audio` | string | No | `on` | `on` or `off` |
|
||||
|
||||
Either (`start_frame`+`end_frame`) OR (`start_time`+`end_time`) must be provided.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Clip by frame range (primary)
|
||||
curl -s "$API/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/clip?start_frame=0&end_frame=47" \
|
||||
-H "Authorization: Bearer $JWT" -o clip.ts
|
||||
|
||||
# Clip by time range (fallback)
|
||||
curl -s "$API/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/clip?start_time=30&end_time=45" \
|
||||
-H "Authorization: Bearer $JWT" -o clip.ts
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
- **200**: `video/mp2t` MPEG-TS stream
|
||||
- **400**: Missing/invalid range parameters
|
||||
- **404**: File not found
|
||||
- **500**: FFmpeg error
|
||||
|
||||
#### Technical Notes
|
||||
|
||||
| Detail | Value |
|
||||
|--------|-------|
|
||||
| **Backend** | FFmpeg (`ffmpeg-full`) |
|
||||
| **Seek** | `-ss` before `-i` (fast keyframe seek) |
|
||||
| **Format** | MPEG-TS (`mpegts` muxer, pipe-safe) |
|
||||
| **Codec** | H.264 + AAC |
|
||||
| **Cache** | `Cache-Control: public, max-age=86400` (24h) |
|
||||
|
||||
### Video vs Clip: Quality & Format Comparison
|
||||
|
||||
Both endpoints support time range extraction, but serve different use cases:
|
||||
|
||||
| Feature | `/video` | `/clip` |
|
||||
|---------|----------|---------|
|
||||
| **No params** | Streams full file (Range seek) | Returns 400 (params required) |
|
||||
| **HTTP Range** | ✅ Supported | ❌ Not supported |
|
||||
| **Encoding** | `-c copy` (zero encoding) | `-c:v libx264 -c:a aac` (re-encode) |
|
||||
| **Quality** | Original (bit-exact, zero loss) | Compressed (default CRF ≈ 23) |
|
||||
| **Format** | `video/mp4` | `video/mp2t` (MPEG-TS) |
|
||||
| **Speed** | Fast (no computation) | Slower (encoding required) |
|
||||
| **Frame control** | Time-based (`dur = (ef-sf)/fps`) | Precise (`-vframes`) |
|
||||
| **Debug mode** | ❌ | ✅ `mode=debug` overlay |
|
||||
| **Cache** | ❌ | ✅ `max-age=86400` |
|
||||
|
||||
#### Usage Recommendation
|
||||
|
||||
| Scenario | Use |
|
||||
|----------|-----|
|
||||
| Full video streaming / player seek | `/video` |
|
||||
| Quick preview clip (zero quality loss) | `/video?start_frame=...&end_frame=...` |
|
||||
| Debug frame verification / text overlay | `/clip?mode=debug` |
|
||||
| Precise frame count control | `/clip` |
|
||||
| CDN cacheable clip | `/clip` |
|
||||
|
||||
---
|
||||
|
||||
| Detail | Value |
|
||||
|--------|-------|
|
||||
| **Backend** | FFmpeg (`ffmpeg-full`) |
|
||||
| **Filter** | `select=eq(n\,FRAME)` to select frame, optional `crop=W:H:X:Y` |
|
||||
| **Output** | Single JPEG via pipe (`image2pipe`, `mjpeg` codec) |
|
||||
| **Cache** | `Cache-Control: public, max-age=86400` (24h) |
|
||||
| **Frame number** | Zero-based (`frame=0` = first frame of video) |
|
||||
|
||||
---
|
||||
*Updated: 2026-05-19 12:49:24*
|
||||
@@ -1,109 +0,0 @@
|
||||
<!-- module: tmdb -->
|
||||
<!-- description: TMDb enrichment endpoints — prefetch, probe, resource, check -->
|
||||
<!-- depends: 01_auth, 03_register -->
|
||||
|
||||
## TMDb Enrichment
|
||||
|
||||
> **Offline operation**: TMDb prefetch now checks local identity files first (`identities/_index.json` + `*.tmdb.json`).
|
||||
> If local files exist, no external API call is made. Internet is only needed for initial data seeding.
|
||||
|
||||
### Overview
|
||||
|
||||
TMDb enrichment is an optional identity enrichment step that can be run after Pipeline face detection completes. The workflow is:
|
||||
|
||||
1. **Prefetch** (requires internet): Download movie cast data from TMDb API → cache to `{file_uuid}.tmdb.json`
|
||||
2. **Probe**: Read local cache → create identities for **all** cast members (`source='tmdb'`) + save `identity.json` + download profile image to `{OUTPUT}/identities/{uuid}/profile.jpg`
|
||||
3. **Match**: The worker automatically matches video faces against TMDb identities when `MOMENTRY_TMDB_PROBE_ENABLED=true`
|
||||
|
||||
### `POST /api/v1/agents/tmdb/prefetch`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Fetch TMDb cast data for a registered file and cache it locally. This is the only step requiring internet access.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `file_uuid` | string | Yes | File UUID to enrich |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/agents/tmdb/prefetch" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"file_uuid": "'"$FILE_UUID"'"}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{"success": true, "file_uuid": "...", "cache_path": "/output/...tmdb.json"}
|
||||
```
|
||||
|
||||
### `POST /api/v1/file/:file_uuid/tmdb-probe`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: file-level
|
||||
|
||||
Read local TMDb cache and create/update identities. Requires prefetch to have been run first.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/file/$FILE_UUID/tmdb-probe" \
|
||||
-H "X-API-Key: $KEY" | jq '{identities_created, movie_title}'
|
||||
```
|
||||
|
||||
#### Response (200 — identities created)
|
||||
|
||||
```json
|
||||
{"success": true, "identities_created": 15, "movie_title": "Charade"}
|
||||
```
|
||||
|
||||
#### Response (200 — no cache)
|
||||
|
||||
```json
|
||||
{"success": false, "message": "No TMDb cache found. Run tmdb-prefetch first."}
|
||||
```
|
||||
|
||||
### `GET /api/v1/resource/tmdb`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
View TMDb resource status including configuration, identity counts, and cache file count.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s "$API/api/v1/resource/tmdb" -H "X-API-Key: $KEY" \
|
||||
| jq '{identities_seeded, cache_files}'
|
||||
```
|
||||
|
||||
### `POST /api/v1/resource/tmdb/check`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
Ping the TMDb API to verify connectivity and measure latency.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/resource/tmdb/check" \
|
||||
-H "X-API-Key: $KEY" | jq '.status'
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"api_key_configured": true,
|
||||
"enabled": false,
|
||||
"api_reachable": true,
|
||||
"api_latency_ms": 120
|
||||
}
|
||||
```
|
||||
@@ -1,178 +0,0 @@
|
||||
<!-- module: pipeline -->
|
||||
<!-- description: Pipeline processors, ingestion status, stats endpoints -->
|
||||
<!-- depends: 01_auth -->
|
||||
|
||||
## Pipeline
|
||||
|
||||
### Dependency Graph
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Processors["10 Processors"]
|
||||
Cut[Cut] --> ASR[ASR]
|
||||
ASR --> ASRX[ASRX]
|
||||
ASRX --> Story[Story]
|
||||
Cut --> Story
|
||||
YOLO[YOLO] --> VisualChunk[VisualChunk]
|
||||
VisualChunk --> Story
|
||||
Face[Face] --> Story
|
||||
Story --> FiveW1H[5W1H]
|
||||
OCR[OCR]
|
||||
Pose[Pose]
|
||||
end
|
||||
|
||||
subgraph Ingestion["入庫 (Post-Processing)"]
|
||||
ASR --> Rule1[Rule 1 Sentence]
|
||||
ASRX --> Rule1
|
||||
Rule1 --> Vectorize[Auto-Vectorize]
|
||||
Rule1 --> Phase1[Phase 1 Pack]
|
||||
|
||||
Cut --> Rule3[Rule 3 Scene]
|
||||
ASR --> Rule3
|
||||
|
||||
Face --> Trace[Face Trace]
|
||||
Trace --> Qdrant[Qdrant Sync]
|
||||
Trace --> TraceChunks[Trace Chunks]
|
||||
Trace --> TKG[TKG Builder]
|
||||
|
||||
Face --> TMDbMatch[TMDb Match]
|
||||
Face --> SceneMeta[Scene Metadata]
|
||||
YOLO --> SceneMeta
|
||||
Face --> IdentityAgent[Identity Agent]
|
||||
ASRX --> IdentityAgent
|
||||
|
||||
Cut --> Agent5W1H[5W1H Agent]
|
||||
ASR --> Agent5W1H
|
||||
Agent5W1H --> Phase2[Phase 2 Pack]
|
||||
end
|
||||
|
||||
style Processors fill:#1a1a2e,stroke:#e94560
|
||||
style Ingestion fill:#16213e,stroke:#0f3460
|
||||
```
|
||||
|
||||
### Pipeline Completion Flow
|
||||
|
||||
The pipeline is **not complete** until both the 10 processors AND the 入庫 (ingestion) steps have finished. The worker polls every 3 seconds and only marks the job as `completed` when all ingestion steps verify OK.
|
||||
|
||||
```
|
||||
10 processors done
|
||||
↓ (job status stays "running")
|
||||
Algorithm 1 Trigger: Rule 1 + Vectorize + Phase 1 Pack
|
||||
↓ (job runs in parallel)
|
||||
Algorithm 2 Trigger: Face Trace → TKG, Scene Metadata, Identity Agent, 5W1H Agent
|
||||
↓ (poll checks every 3s)
|
||||
Ingestion verification: rule1 ✓ vectorize ✓ rule3 ✓ face_trace ✓ tkg ✓ scene_meta ✓ 5w1h ✓
|
||||
↓
|
||||
job status = "completed"
|
||||
```
|
||||
|
||||
### 10 Processor Stages
|
||||
|
||||
| # | Processor | Depends On | Description |
|
||||
|---|-----------|------------|-------------|
|
||||
| 1 | `Cut` | — | Scene boundary detection (PySceneDetect) |
|
||||
| 2 | `ASR` | Cut | Automatic speech recognition (faster-whisper) |
|
||||
| 3 | `ASRX` | ASR | Speaker diarization + ASR refinement |
|
||||
| 4 | `YOLO` | — | Object detection (YOLOv8) |
|
||||
| 5 | `OCR` | — | Optical character recognition |
|
||||
| 6 | `Face` | — | Face detection + recognition (InsightFace + CoreML) |
|
||||
| 7 | `Pose` | — | Pose estimation |
|
||||
| 8 | `VisualChunk` | YOLO | Visual object chunking |
|
||||
| 9 | `Story` | ASRX + Cut + YOLO + Face | Narrative scene summarization (LLM, with embedding) |
|
||||
| 10 | `5W1H` | Story | Who/What/When/Where/Why extraction (LLM, with embedding) |
|
||||
|
||||
### 入庫 (Post-Processing / Ingestion)
|
||||
|
||||
These steps run after the 10 processors and are **required for pipeline completion**. The worker checks all of them before marking the job as done.
|
||||
|
||||
| # | Step | Triggers When | Verification |
|
||||
|---|------|--------------|-------------|
|
||||
| 1 | **Rule 1 Sentence Chunking** | ASR + ASRX done | `chunk` table has rows with `chunk_type = 'sentence'` |
|
||||
| 2 | **Auto-Vectorize** | Rule 1 done | `chunk.embedding` IS NOT NULL for sentence chunks |
|
||||
| 3 | **Phase 1 Pack** | Rule 1 done | `release_pack.py --phase 1` executed |
|
||||
| 4 | **Rule 3 Scene Chunking** | All 10 processors done + Cut + ASR | `chunk` table has rows with `chunk_type = 'cut'` |
|
||||
| 5 | **Face Trace** | All 10 processors done + Face | `face_detections.trace_id` IS NOT NULL |
|
||||
| 6 | **Qdrant Face Sync** | Face Trace done | Qdrant face_embedding collection populated |
|
||||
| 7 | **Trace Chunks** | Face Trace done | `chunk` table has rows with `chunk_type = 'trace'` |
|
||||
| 8 | **TKG Builder** | Face Trace done | `tkg_nodes` + `tkg_edges` tables have rows |
|
||||
| 9 | **TMDb Face Matching** | TMDb enabled + Face done | `face_detections.identity_id` IS NOT NULL |
|
||||
| 10 | **Heuristic Scene Metadata** | Face + YOLO done | `{file_uuid}.scene_meta.json` exists on disk |
|
||||
| 11 | **Identity Agent** | Face + ASRX done | `identities` with `source = 'identity_agent'` |
|
||||
| 12 | **5W1H Agent** | Cut + ASR done | `chunk.summary_text` IS NOT NULL for cut chunks |
|
||||
| 13 | **Release Pack** | 5W1H Agent done | `release_pack.py --phase 2` executed |
|
||||
|
||||
### Ingestion Status
|
||||
|
||||
Check real-time ingestion status for a file:
|
||||
|
||||
```bash
|
||||
curl "$API/api/v1/stats/ingestion-status/{file_uuid}"
|
||||
```
|
||||
|
||||
Returns per-step `done` / `pending` status with detail counts.
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3003/api/v1/stats/ingestion-status/bd80fec9c42afb0307eb28f22c64c76a" | jq '.steps[] | {name, status, detail}'
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"file_uuid": "bd80fec9c42afb0307eb28f22c64c76a",
|
||||
"steps": [
|
||||
{ "name": "rule1_sentence", "status": "pending", "detail": "0 sentence chunks" },
|
||||
{ "name": "auto_vectorize", "status": "pending", "detail": "0 embedded" },
|
||||
{ "name": "rule3_scene", "status": "pending", "detail": "0 scene chunks" },
|
||||
{ "name": "face_trace", "status": "pending", "detail": "0 traces" },
|
||||
{ "name": "trace_chunks", "status": "pending", "detail": "0 trace chunks" },
|
||||
{ "name": "tkg", "status": "pending", "detail": "0 nodes, 0 edges" },
|
||||
{ "name": "identity_match", "status": "pending", "detail": "0 identities" },
|
||||
{ "name": "scene_metadata", "status": "pending", "detail": null },
|
||||
{ "name": "5w1h", "status": "pending", "detail": "0 scenes with 5W1H" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Stats Endpoints
|
||||
|
||||
| Method | Endpoint | Auth | Description |
|
||||
|--------|----------|------|-------------|
|
||||
| GET | `/api/v1/stats/sftpgo` | No | SFTPGo service status |
|
||||
| GET | `/api/v1/stats/ingestion-status/:file_uuid` | No | Per-file ingestion checklist |
|
||||
|
||||
### Configuration
|
||||
|
||||
### `POST /api/v1/config/cache`
|
||||
|
||||
**Auth**: Required
|
||||
**Scope**: system-level
|
||||
|
||||
Toggle the Redis cache on or off.
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `enabled` | boolean | Yes | `true` to enable, `false` to disable |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$API/api/v1/config/cache" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-d '{"enabled": false}'
|
||||
```
|
||||
|
||||
### Unmounted Routes
|
||||
|
||||
The following routes are defined in source code but are **NOT** currently mounted in the router:
|
||||
|
||||
| Endpoint | Source file |
|
||||
|----------|-------------|
|
||||
| `/api/v1/search/persons` | `universal_search.rs` (not mounted) |
|
||||
| `/api/v1/who` | `who.rs` |
|
||||
| `/api/v1/who/candidates` | `who.rs` |
|
||||
@@ -1,57 +0,0 @@
|
||||
<!-- module: error_codes -->
|
||||
<!-- description: Standard API error codes -->
|
||||
<!-- depends: -->
|
||||
|
||||
## Error Response Format
|
||||
|
||||
All API errors follow this JSON structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "E001_NOT_FOUND",
|
||||
"message": "Resource not found",
|
||||
"details": {"resource": "file_uuid", "value": "abc"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Code List
|
||||
|
||||
### Generic Errors (E0xx)
|
||||
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `E001_NOT_FOUND` | 404 | Resource not found (file, identity, chunk) |
|
||||
| `E002_DUPLICATE` | 409 | Resource already exists |
|
||||
| `E003_VALIDATION` | 400 | Request parameter validation failed |
|
||||
| `E004_UNAUTHORIZED` | 401 | Invalid API key or token |
|
||||
| `E005_INTERNAL` | 500 | Internal server error |
|
||||
|
||||
### Processor Errors (E1xx)
|
||||
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `E101_PROCESSOR_FAIL` | 500 | Python script execution failed |
|
||||
| `E102_TIMEOUT` | 504 | Processing timeout |
|
||||
| `E103_RESUME_FAIL` | 500 | Resume failed (checkpoint not found) |
|
||||
| `E104_NO_VIDEO` | 400 | Video file path not found |
|
||||
|
||||
### Identity Errors (E2xx)
|
||||
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `E201_FACE_NOT_FOUND` | 404 | Face detection not found |
|
||||
| `E202_MERGE_CONFLICT` | 409 | Identity merge conflict |
|
||||
| `E203_CANDIDATE_EMPTY` | 404 | No candidates available for confirmation |
|
||||
|
||||
### TMDb Errors (E3xx)
|
||||
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `E301_TMDB_NO_KEY` | 400 | `TMDB_API_KEY` environment variable not set |
|
||||
| `E302_TMDB_UNREACHABLE` | 502 | TMDb API unreachable or timed out |
|
||||
| `E303_TMDB_CACHE_NOT_FOUND` | 200 | No local TMDb cache; run prefetch first |
|
||||
| `E304_TMDB_PROBE_FAILED` | 500 | TMDb probe execution failed |
|
||||
| `E305_TMDB_MOVIE_NOT_FOUND` | 404 | No matching TMDb movie found from filename |
|
||||
@@ -1,118 +0,0 @@
|
||||
# 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 |
|
||||
|
||||
@@ -1,63 +0,0 @@
|
||||
# {Module Name} — API Workspace Module
|
||||
|
||||
> Use this template when adding or editing API endpoint documentation modules.
|
||||
|
||||
## Module Metadata
|
||||
|
||||
Every module MUST start with:
|
||||
|
||||
```markdown
|
||||
<!-- module: <short_name> -->
|
||||
<!-- description: One-line description of what this module covers -->
|
||||
<!-- depends: <comma-separated list of dependency module names> -->
|
||||
```
|
||||
|
||||
## Endpoint Template
|
||||
|
||||
Each endpoint MUST use this structure:
|
||||
|
||||
### `METHOD /path/to/endpoint`
|
||||
|
||||
**Auth**: Required / Optional / Public
|
||||
|
||||
**Scope**: file-level / identity-level / system-level
|
||||
|
||||
#### Request Parameters
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `param1` | string | Yes | — | Description |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# brief description of what this example demonstrates
|
||||
curl -s -X METHOD "$API/path" \
|
||||
-H "X-API-Key: $KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"param1": "value"}'
|
||||
```
|
||||
|
||||
#### Response (200)
|
||||
|
||||
```json
|
||||
{ "success": true }
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `success` | boolean | Always true on 200 |
|
||||
|
||||
#### Error Codes
|
||||
|
||||
| Code | HTTP | When |
|
||||
|------|------|------|
|
||||
| E0xx | 4xx | Description |
|
||||
|
||||
## Rules
|
||||
|
||||
1. Each module file covers ONE topic group (e.g., `09_tmdb.md` = all TMDb endpoints)
|
||||
2. Use `$API` and `$KEY` in all curl examples
|
||||
3. Use `$FILE_UUID`, `$IDENTITY_UUID` variables for UUID examples
|
||||
4. Module filename = `NN_topic.md` (NN = execution order, 01-99)
|
||||
5. `depends` metadata = which modules must be assembled before this one
|
||||
@@ -1,225 +0,0 @@
|
||||
#!/opt/homebrew/bin/python3.11
|
||||
"""Build HTML documentation from module source files."""
|
||||
import os, markdown, re, glob, shutil
|
||||
|
||||
MODULES_DIR = os.path.join(os.path.dirname(__file__), "..", "docs_v1.0", "API_WORKSPACE", "modules")
|
||||
DOC_DIR = os.path.join(os.path.dirname(__file__), "..", "docs_v1.0", "doc")
|
||||
DOC_DEV_DIR = os.path.join(os.path.dirname(__file__), "..", "docs_v1.0", "doc_developer")
|
||||
|
||||
# User-facing modules (no developer content)
|
||||
USER_MODULES = {
|
||||
"01_auth", "02_health", "03_register", "04_lookup", "05_process",
|
||||
"06_search", "07_identity", "08_identity_agent", "08_media",
|
||||
"09_tmdb", "10_pipeline", "12_agent",
|
||||
}
|
||||
|
||||
|
||||
def md_to_html(md_text: str) -> str:
|
||||
"""Convert Markdown to HTML."""
|
||||
html = markdown.markdown(md_text, extensions=['fenced_code', 'tables', 'codehilite'])
|
||||
# Wrap tables
|
||||
html = re.sub(r'<table>', '<table class="table">', html)
|
||||
return html
|
||||
|
||||
def build_index(files, dev=False):
|
||||
"""Build index.html."""
|
||||
links = []
|
||||
for fname in sorted(files):
|
||||
name = os.path.splitext(fname)[0]
|
||||
label = MODULE_LABELS.get(name, name.replace("_", " ").title())
|
||||
if "｜" in label:
|
||||
cn, en = label.split("｜", 1)
|
||||
else:
|
||||
cn, en = label, ""
|
||||
html_name = fname.replace(".md", ".html")
|
||||
links.append(f'<tr onclick="window.location=\'{html_name}\'" style="cursor:pointer"><td class="cn">{cn}</td><td class="en">{en}</td></tr>')
|
||||
|
||||
title = "Momentry API 開發者文件" if dev else "Momentry API 文件"
|
||||
subtitle = "開發者專用" if dev else "API 參考手冊 — 登入後可瀏覽各模組文件"
|
||||
|
||||
return f"""<!DOCTYPE html>
|
||||
<html lang="zh-TW">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>{title}</title>
|
||||
<style>
|
||||
* {{ margin: 0; padding: 0; box-sizing: border-box; }}
|
||||
body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }}
|
||||
.container {{ max-width: 900px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }}
|
||||
h1 {{ font-size: 28px; margin-bottom: 8px; }}
|
||||
p.subtitle {{ color: #666; margin-bottom: 24px; }}
|
||||
table {{ width: 100%; border-collapse: collapse; }}
|
||||
tr {{ border-bottom: 1px solid #eee; }}
|
||||
tr:last-child {{ border: none; }}
|
||||
td {{ padding: 10px 0; }}
|
||||
td.cn {{ width: 140px; font-weight: 600; color: #333; }}
|
||||
td.en {{ color: #666; font-size: 14px; }}
|
||||
a {{ color: #0066cc; text-decoration: none; display: block; }}
|
||||
a:hover td {{ background: #f8f8f8; border-radius: 4px; }}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<h1>{title}</h1>
|
||||
<p class="subtitle">{subtitle}</p>
|
||||
<table>{"".join(links)}</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>"""
|
||||
|
||||
MODULE_LABELS = {
|
||||
"01_auth": "安全認證｜Authentication",
|
||||
"02_health": "健康檢查｜Health",
|
||||
"03_register": "檔案註冊｜File Registration",
|
||||
"04_lookup": "檔案屬性查詢｜File Lookup",
|
||||
"05_process": "處理流程｜Processing",
|
||||
"06_search": "搜尋功能｜Search",
|
||||
"07_identity": "身份識別｜Identity",
|
||||
"08_identity_agent": "智能身份綁定｜Smart Identity Binding",
|
||||
"08_media": "串流與截圖｜Streaming & Thumbnails",
|
||||
"09_tmdb": "TMDb 整合｜TMDb Integration",
|
||||
"10_pipeline": "生產線｜Pipeline",
|
||||
"11_error_codes": "錯誤碼｜Error Codes",
|
||||
"12_agent": "智慧代理｜AI Agents",
|
||||
}
|
||||
|
||||
def build_html(md_text: str, title: str) -> str:
|
||||
"""Wrap MD content in HTML page."""
|
||||
content = md_to_html(md_text)
|
||||
return f"""<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>{title} - Momentry API Docs</title>
|
||||
<style>
|
||||
* {{ margin: 0; padding: 0; box-sizing: border-box; }}
|
||||
body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }}
|
||||
.container {{ max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }}
|
||||
h1 {{ font-size: 24px; margin: 24px 0 12px; }}
|
||||
h2 {{ font-size: 20px; margin: 20px 0 10px; color: #222; }}
|
||||
h3 {{ font-size: 16px; margin: 16px 0 8px; color: #444; }}
|
||||
p {{ line-height: 1.6; margin: 8px 0; }}
|
||||
table {{ border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }}
|
||||
th, td {{ border: 1px solid #ddd; padding: 8px 12px; text-align: left; }}
|
||||
th {{ background: #f0f0f0; font-weight: 600; }}
|
||||
code {{ background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }}
|
||||
pre {{ background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }}
|
||||
pre code {{ background: none; padding: 0; }}
|
||||
a {{ color: #0066cc; }}
|
||||
.back {{ display: inline-block; margin-bottom: 20px; color: #666; }}
|
||||
.back:hover {{ color: #333; }}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<a class="back" href="index.html">← Back to index</a>
|
||||
{content}
|
||||
</div>
|
||||
</body>
|
||||
</html>"""
|
||||
|
||||
def login_page() -> str:
|
||||
return """<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Login - Momentry Docs</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; display: flex; justify-content: center; align-items: center; height: 100vh; }
|
||||
.card { background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; width: 360px; }
|
||||
h1 { font-size: 24px; margin-bottom: 24px; text-align: center; }
|
||||
input { width: 100%; padding: 10px 12px; margin-bottom: 12px; border: 1px solid #ddd; border-radius: 6px; font-size: 14px; }
|
||||
button { width: 100%; padding: 10px; background: #0066cc; color: white; border: none; border-radius: 6px; font-size: 16px; cursor: pointer; }
|
||||
button:hover { background: #0052a3; }
|
||||
.error { color: #cc0000; font-size: 13px; margin-bottom: 12px; display: none; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="card">
|
||||
<h1>Momentry Docs</h1>
|
||||
<form id="loginForm">
|
||||
<input type="text" id="username" placeholder="Username" value="demo" required>
|
||||
<input type="password" id="password" placeholder="Password" value="demo" required>
|
||||
<div class="error" id="error">Invalid credentials</div>
|
||||
<button type="submit">Login</button>
|
||||
</form>
|
||||
</div>
|
||||
<script>
|
||||
document.getElementById('loginForm').onsubmit = async function(e) {
|
||||
e.preventDefault();
|
||||
const resp = await fetch('/api/v1/auth/login', {
|
||||
method: 'POST',
|
||||
headers: {'Content-Type': 'application/json'},
|
||||
body: JSON.stringify({
|
||||
username: document.getElementById('username').value,
|
||||
password: document.getElementById('password').value
|
||||
})
|
||||
});
|
||||
if (resp.ok) {
|
||||
window.location.href = '/doc/index.html';
|
||||
} else {
|
||||
document.getElementById('error').style.display = 'block';
|
||||
}
|
||||
};
|
||||
</script>
|
||||
</body>
|
||||
</html>"""
|
||||
|
||||
def main():
|
||||
# Clean and recreate doc dirs
|
||||
for d in [DOC_DIR, DOC_DEV_DIR]:
|
||||
if os.path.exists(d):
|
||||
shutil.rmtree(d)
|
||||
os.makedirs(d)
|
||||
|
||||
md_files = sorted(glob.glob(os.path.join(MODULES_DIR, "*.md")))
|
||||
if not md_files:
|
||||
print(f"No MD files found in {MODULES_DIR}")
|
||||
return
|
||||
|
||||
user_html = []
|
||||
dev_html = []
|
||||
for md_path in md_files:
|
||||
with open(md_path) as f:
|
||||
md_text = f.read()
|
||||
fname = os.path.basename(md_path)
|
||||
stem = os.path.splitext(fname)[0]
|
||||
|
||||
# Skip template
|
||||
if stem == "_template":
|
||||
continue
|
||||
|
||||
# Skip error codes (developer-only)
|
||||
if stem == "11_error_codes":
|
||||
dev_only = True
|
||||
else:
|
||||
dev_only = stem not in USER_MODULES
|
||||
|
||||
title = stem.replace("_", " ").title()
|
||||
html = build_html(md_text, title)
|
||||
|
||||
if dev_only:
|
||||
out_path = os.path.join(DOC_DEV_DIR, fname.replace(".md", ".html"))
|
||||
with open(out_path, "w") as f:
|
||||
f.write(html)
|
||||
dev_html.append(fname)
|
||||
print(f" [dev] {fname}")
|
||||
else:
|
||||
out_path = os.path.join(DOC_DIR, fname.replace(".md", ".html"))
|
||||
with open(out_path, "w") as f:
|
||||
f.write(html)
|
||||
user_html.append(fname)
|
||||
print(f" [doc] {fname}")
|
||||
|
||||
# Build indexes + login page
|
||||
for d, files, label in [(DOC_DIR, user_html, "User"), (DOC_DEV_DIR, dev_html, "Dev")]:
|
||||
index = build_index(files)
|
||||
with open(os.path.join(d, "index.html"), "w") as f:
|
||||
f.write(index)
|
||||
with open(os.path.join(d, "login.html"), "w") as f:
|
||||
f.write(login_page())
|
||||
print(f" {label}: {len(files)} pages -> {d}")
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,148 +0,0 @@
|
||||
#!/bin/bash
|
||||
# sync_dev_to_public.sh — 比對 dev/public schema，同步 pipeline 資料
|
||||
# Usage: ./sync_dev_to_public.sh [check|sync] [file_uuid]
|
||||
|
||||
PSQL="/opt/homebrew/opt/libpq/bin/psql"
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCHEMA="${MOMENTRY_DB_SCHEMA:-dev}"
|
||||
DB_URL="${DATABASE_URL:-postgres://accusys@localhost:5432/momentry}"
|
||||
MODE="${1:-check}"
|
||||
FILE_UUID="${2:-}"
|
||||
|
||||
TABLES=("videos" "chunk" "face_detections" "processor_results" "monitor_jobs"
|
||||
"identities" "identity_bindings" "tkg_nodes" "tkg_edges")
|
||||
|
||||
TARGET="public"
|
||||
|
||||
if [ -z "$FILE_UUID" ]; then
|
||||
echo "Usage: $0 [check|sync] <file_uuid>"
|
||||
echo ""
|
||||
echo "Examples:"
|
||||
echo " $0 check bd80fec92b0b6963d177a2c55bf713e2"
|
||||
echo " $0 sync bd80fec92b0b6963d177a2c55bf713e2"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "=== Schema Sync: $SCHEMA → $TARGET ==="
|
||||
echo "File UUID: $FILE_UUID"
|
||||
echo "Mode: $MODE"
|
||||
echo ""
|
||||
|
||||
check_table() {
|
||||
local table=$1
|
||||
local col=$2
|
||||
local src_count dev_count pub_count
|
||||
|
||||
dev_count=$($PSQL -At "$DB_URL" -c "SELECT COUNT(*) FROM ${SCHEMA}.${table} WHERE ${col} = '${FILE_UUID}';" 2>/dev/null || echo "ERROR")
|
||||
pub_count=$($PSQL -At "$DB_URL" -c "SELECT COUNT(*) FROM ${TARGET}.${table} WHERE ${col} = '${FILE_UUID}';" 2>/dev/null || echo "ERROR")
|
||||
|
||||
if [ "$dev_count" = "ERROR" ] || [ "$pub_count" = "ERROR" ]; then
|
||||
echo " ⚠️ $table — query error (table may not exist in $TARGET)"
|
||||
return 1
|
||||
fi
|
||||
|
||||
if [ "$dev_count" -eq "$pub_count" ]; then
|
||||
echo " ✅ $table — $dev_count rows (match)"
|
||||
return 0
|
||||
else
|
||||
echo " ❌ $table — dev=$dev_count pub=$pub_count (MISMATCH)"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
sync_table() {
|
||||
local table=$1
|
||||
local col=$2
|
||||
local src_count dev_count pub_count
|
||||
|
||||
dev_count=$($PSQL -At "$DB_URL" -c "SELECT COUNT(*) FROM ${SCHEMA}.${table} WHERE ${col} = '${FILE_UUID}';" 2>/dev/null || echo "0")
|
||||
pub_count=$($PSQL -At "$DB_URL" -c "SELECT COUNT(*) FROM ${TARGET}.${table} WHERE ${col} = '${FILE_UUID}';" 2>/dev/null || echo "0")
|
||||
|
||||
if [ "$dev_count" = "0" ]; then
|
||||
echo " ⏭️ $table — dev has 0 rows, skipping"
|
||||
return
|
||||
fi
|
||||
|
||||
if [ "$dev_count" -eq "$pub_count" ]; then
|
||||
echo " ✅ $table — already synced ($dev_count rows)"
|
||||
return
|
||||
fi
|
||||
|
||||
echo " 🔄 Syncing $table: dev=$dev_count → pub=$pub_count ..."
|
||||
|
||||
# Delete existing public rows, insert from dev
|
||||
$PSQL "$DB_URL" -q -c "DELETE FROM ${TARGET}.${table} WHERE ${col} = '${FILE_UUID}';" 2>/dev/null || true
|
||||
|
||||
# Get columns list (excluding id for SERIAL)
|
||||
COLS=$($PSQL -At "$DB_URL" -c "
|
||||
SELECT string_agg(column_name, ', ' ORDER BY ordinal_position)
|
||||
FROM information_schema.columns
|
||||
WHERE table_schema='${SCHEMA}' AND table_name='${table}'
|
||||
AND column_name != 'id'
|
||||
AND is_updatable='YES';
|
||||
")
|
||||
|
||||
$PSQL "$DB_URL" -q -c "
|
||||
INSERT INTO ${TARGET}.${table} (${COLS})
|
||||
SELECT ${COLS}
|
||||
FROM ${SCHEMA}.${table}
|
||||
WHERE ${col} = '${FILE_UUID}';
|
||||
" 2>/dev/null && echo " ✅ $table synced" || echo " ❌ $table sync FAILED"
|
||||
}
|
||||
|
||||
echo "=== Checking Tables ==="
|
||||
echo ""
|
||||
MISMATCH=0
|
||||
for table in "${TABLES[@]}"; do
|
||||
# Determine the UUID column name for each table
|
||||
case "$table" in
|
||||
videos) col="file_uuid" ;;
|
||||
chunk) col="file_uuid" ;;
|
||||
face_detections) col="file_uuid" ;;
|
||||
processor_results) col="file_uuid" ;;
|
||||
monitor_jobs) col="uuid" ;;
|
||||
identities) col="uuid" ;; # identities.uuid is UUID type
|
||||
identity_bindings) col="uuid" ;;
|
||||
tkg_nodes) col="file_uuid" ;;
|
||||
tkg_edges) col="file_uuid" ;;
|
||||
*) col="file_uuid" ;;
|
||||
esac
|
||||
|
||||
if ! check_table "$table" "$col"; then
|
||||
MISMATCH=$((MISMATCH + 1))
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
if [ "$MISMATCH" -eq 0 ]; then
|
||||
echo "✅ All tables in sync"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [ "$MODE" != "sync" ]; then
|
||||
echo "⚠️ $MISMATCH table(s) have mismatches. Run '$0 sync $FILE_UUID' to fix."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "=== Syncing Tables ==="
|
||||
echo ""
|
||||
for table in "${TABLES[@]}"; do
|
||||
case "$table" in
|
||||
videos) col="file_uuid" ;;
|
||||
chunk) col="file_uuid" ;;
|
||||
face_detections) col="file_uuid" ;;
|
||||
processor_results) col="file_uuid" ;;
|
||||
monitor_jobs) col="uuid" ;;
|
||||
identities) col="uuid" ;;
|
||||
identity_bindings) col="uuid" ;;
|
||||
tkg_nodes) col="file_uuid" ;;
|
||||
tkg_edges) col="file_uuid" ;;
|
||||
*) col="file_uuid" ;;
|
||||
esac
|
||||
sync_table "$table" "$col"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "✅ Sync complete"
|
||||
@@ -1,174 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""批量更新 Qdrant collection 中的 file_uuid (舊→新)"""
|
||||
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
|
||||
QDRANT_URL = "http://localhost:6333"
|
||||
|
||||
# UUID mapping: 舊 → 新
|
||||
UUID_MAP = {
|
||||
"aeed71342a899fe4b4c57b7d41bcb692": [
|
||||
"bd80fec92b0b6963d177a2c55bf713e2",
|
||||
],
|
||||
}
|
||||
|
||||
# Collections to process
|
||||
COLLECTIONS = [
|
||||
"momentry_dev_v1",
|
||||
"momentry_dev_stories",
|
||||
"momentry_dev_voice",
|
||||
"momentry_dev_rule1_v2",
|
||||
"momentry_dev_faces",
|
||||
"sentence_story",
|
||||
"sentence_summary",
|
||||
]
|
||||
|
||||
|
||||
def qdrant_get(path: str) -> dict:
|
||||
res = subprocess.run(
|
||||
["curl", "-s", "-X", "GET", f"{QDRANT_URL}{path}"],
|
||||
capture_output=True, text=True
|
||||
)
|
||||
return json.loads(res.stdout) if res.stdout.strip() else {}
|
||||
|
||||
|
||||
def qdrant_post(path: str, body: dict) -> dict:
|
||||
tmp = "/tmp/qdrant_post.json"
|
||||
with open(tmp, "w") as f:
|
||||
json.dump(body, f)
|
||||
res = subprocess.run(
|
||||
["curl", "-s", "-X", "POST", f"{QDRANT_URL}{path}",
|
||||
"-H", "Content-Type: application/json", "-d", f"@{tmp}"],
|
||||
capture_output=True, text=True
|
||||
)
|
||||
return json.loads(res.stdout) if res.stdout.strip() else {}
|
||||
|
||||
|
||||
def qdrant_put(path: str, body: dict) -> dict:
|
||||
tmp = "/tmp/qdrant_update.json"
|
||||
with open(tmp, "w") as f:
|
||||
json.dump(body, f)
|
||||
res = subprocess.run(
|
||||
["curl", "-s", "-X", "PUT", f"{QDRANT_URL}{path}",
|
||||
"-H", "Content-Type: application/json", "-d", f"@{tmp}"],
|
||||
capture_output=True, text=True
|
||||
)
|
||||
return json.loads(res.stdout) if res.stdout.strip() else {}
|
||||
|
||||
|
||||
def scroll_all(collection: str, filter_old: dict) -> list:
|
||||
"""Scroll all matching points from a collection"""
|
||||
points = []
|
||||
offset = None
|
||||
while True:
|
||||
body = {
|
||||
"limit": 1000,
|
||||
"with_payload": True,
|
||||
"with_vector": True,
|
||||
"filter": filter_old,
|
||||
}
|
||||
if offset:
|
||||
body["offset"] = offset
|
||||
result = qdrant_post(f"/collections/{collection}/points/scroll", body)
|
||||
batch = result.get("result", {}).get("points", [])
|
||||
points.extend(batch)
|
||||
next_offset = result.get("result", {}).get("next_page_offset")
|
||||
if next_offset is None:
|
||||
break
|
||||
offset = next_offset
|
||||
return points
|
||||
|
||||
|
||||
def update_points(collection: str, points: list, old_uuid: str, new_uuid: str):
|
||||
"""Update file_uuid in payload for the given points"""
|
||||
if not points:
|
||||
return 0
|
||||
|
||||
updated = []
|
||||
for p in points:
|
||||
pl = p.get("payload", {})
|
||||
# Check both 'uuid' and 'file_uuid' fields
|
||||
changed = False
|
||||
if pl.get("uuid") == old_uuid:
|
||||
pl["uuid"] = new_uuid
|
||||
changed = True
|
||||
if pl.get("file_uuid") == old_uuid:
|
||||
pl["file_uuid"] = new_uuid
|
||||
changed = True
|
||||
if changed:
|
||||
updated.append({
|
||||
"id": p["id"],
|
||||
"vector": p["vector"],
|
||||
"payload": pl,
|
||||
})
|
||||
|
||||
if not updated:
|
||||
return 0
|
||||
|
||||
# Update in batches of 500
|
||||
total = len(updated)
|
||||
for i in range(0, total, 500):
|
||||
batch = updated[i:i+500]
|
||||
result = qdrant_put(
|
||||
f"/collections/{collection}/points?wait=true",
|
||||
{"points": batch}
|
||||
)
|
||||
if result.get("status") != "ok":
|
||||
print(f" Error at {i}: {result}")
|
||||
return i
|
||||
return total
|
||||
|
||||
|
||||
def main():
|
||||
for collection in COLLECTIONS:
|
||||
# Check if collection exists
|
||||
info = qdrant_get(f"/collections/{collection}")
|
||||
if "result" not in info:
|
||||
continue
|
||||
|
||||
for old_uuid, new_uuids in UUID_MAP.items():
|
||||
for new_uuid in new_uuids:
|
||||
# Scroll all points with this old UUID
|
||||
filter_body = {
|
||||
"must": [
|
||||
{"should": [
|
||||
{"key": "uuid", "match": {"value": old_uuid}},
|
||||
{"key": "file_uuid", "match": {"value": old_uuid}},
|
||||
]}
|
||||
]
|
||||
}
|
||||
points = scroll_all(collection, filter_body)
|
||||
if not points:
|
||||
continue
|
||||
|
||||
print(f"{collection}: {len(points)} points with UUID {old_uuid[:8]}...")
|
||||
updated = update_points(collection, points, old_uuid, new_uuid)
|
||||
print(f" → {updated} points updated to {new_uuid[:8]}...")
|
||||
|
||||
# Verify
|
||||
print("\n=== Verification ===")
|
||||
for collection in COLLECTIONS:
|
||||
for old_uuid, new_uuids in UUID_MAP.items():
|
||||
for what, uuid in [("old", old_uuid), ("new", new_uuids[0])]:
|
||||
filter_body = {
|
||||
"must": [
|
||||
{"should": [
|
||||
{"key": "uuid", "match": {"value": uuid}},
|
||||
{"key": "file_uuid", "match": {"value": uuid}},
|
||||
]}
|
||||
]
|
||||
}
|
||||
result = qdrant_post(
|
||||
f"/collections/{collection}/points/count",
|
||||
{"filter": filter_body}
|
||||
)
|
||||
cnt = result.get("result", {}).get("count", 0)
|
||||
if cnt > 0:
|
||||
print(f" {collection}: {cnt} points with {what} UUID")
|
||||
print("✅ Done")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Generated
-224
@@ -1,224 +0,0 @@
|
||||
# This file is automatically @generated by Cargo.
|
||||
# It is not intended for manual editing.
|
||||
version = 4
|
||||
|
||||
[[package]]
|
||||
name = "bitflags"
|
||||
version = "2.11.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
|
||||
|
||||
[[package]]
|
||||
name = "bumpalo"
|
||||
version = "3.20.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
|
||||
|
||||
[[package]]
|
||||
name = "cfg-if"
|
||||
version = "1.0.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
|
||||
|
||||
[[package]]
|
||||
name = "doc_wasm"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"pulldown-cmark",
|
||||
"serde",
|
||||
"serde_json",
|
||||
"wasm-bindgen",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "getopts"
|
||||
version = "0.2.24"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
|
||||
dependencies = [
|
||||
"unicode-width",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "itoa"
|
||||
version = "1.0.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
|
||||
|
||||
[[package]]
|
||||
name = "memchr"
|
||||
version = "2.8.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
|
||||
|
||||
[[package]]
|
||||
name = "once_cell"
|
||||
version = "1.21.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
|
||||
|
||||
[[package]]
|
||||
name = "proc-macro2"
|
||||
version = "1.0.106"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
|
||||
dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pulldown-cmark"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "679341d22c78c6c649893cbd6c3278dcbe9fc4faa62fea3a9296ae2b50c14625"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
"getopts",
|
||||
"memchr",
|
||||
"pulldown-cmark-escape",
|
||||
"unicase",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pulldown-cmark-escape"
|
||||
version = "0.11.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
|
||||
|
||||
[[package]]
|
||||
name = "quote"
|
||||
version = "1.0.45"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustversion"
|
||||
version = "1.0.22"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
|
||||
|
||||
[[package]]
|
||||
name = "serde"
|
||||
version = "1.0.228"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
|
||||
dependencies = [
|
||||
"serde_core",
|
||||
"serde_derive",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_core"
|
||||
version = "1.0.228"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
|
||||
dependencies = [
|
||||
"serde_derive",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_derive"
|
||||
version = "1.0.228"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_json"
|
||||
version = "1.0.149"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
|
||||
dependencies = [
|
||||
"itoa",
|
||||
"memchr",
|
||||
"serde",
|
||||
"serde_core",
|
||||
"zmij",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "syn"
|
||||
version = "2.0.117"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "unicase"
|
||||
version = "2.9.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
|
||||
|
||||
[[package]]
|
||||
name = "unicode-ident"
|
||||
version = "1.0.24"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
|
||||
|
||||
[[package]]
|
||||
name = "unicode-width"
|
||||
version = "0.2.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen"
|
||||
version = "0.2.121"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "49ace1d07c165b0864824eee619580c4689389afa9dc9ed3a4c75040d82e6790"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"once_cell",
|
||||
"rustversion",
|
||||
"wasm-bindgen-macro",
|
||||
"wasm-bindgen-shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro"
|
||||
version = "0.2.121"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8e68e6f4afd367a562002c05637acb8578ff2dea1943df76afb9e83d177c8578"
|
||||
dependencies = [
|
||||
"quote",
|
||||
"wasm-bindgen-macro-support",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro-support"
|
||||
version = "0.2.121"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d95a9ec35c64b2a7cb35d3fead40c4238d0940c86d107136999567a4703259f2"
|
||||
dependencies = [
|
||||
"bumpalo",
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn",
|
||||
"wasm-bindgen-shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-shared"
|
||||
version = "0.2.121"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "c4e0100b01e9f0d03189a92b96772a1fb998639d981193d7dbab487302513441"
|
||||
dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "zmij"
|
||||
version = "1.0.21"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
|
||||
@@ -1,18 +0,0 @@
|
||||
[package]
|
||||
name = "doc_wasm"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[lib]
|
||||
crate-type = ["cdylib", "rlib"]
|
||||
|
||||
[dependencies]
|
||||
wasm-bindgen = "0.2"
|
||||
pulldown-cmark = "0.11"
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
|
||||
[profile.release]
|
||||
lto = true
|
||||
opt-level = "s"
|
||||
strip = true
|
||||
@@ -1,29 +0,0 @@
|
||||
use wasm_bindgen::prelude::*;
|
||||
|
||||
#[wasm_bindgen]
|
||||
pub fn render_markdown(md: &str) -> String {
|
||||
let parser = pulldown_cmark::Parser::new(md);
|
||||
let mut html = String::new();
|
||||
pulldown_cmark::html::push_html(&mut html, parser);
|
||||
// wrap tables
|
||||
html = html.replace("<table>", "<table class=\"table\">");
|
||||
html
|
||||
}
|
||||
|
||||
#[wasm_bindgen]
|
||||
pub fn module_list() -> String {
|
||||
serde_json::to_string(&[
|
||||
("01_auth", "安全認證", "Authentication"),
|
||||
("02_health", "健康檢查", "Health"),
|
||||
("03_register", "檔案註冊", "File Registration"),
|
||||
("04_lookup", "檔案屬性查詢", "File Lookup"),
|
||||
("05_process", "處理流程", "Processing"),
|
||||
("06_search", "搜尋功能", "Search"),
|
||||
("07_identity", "身份識別", "Identity"),
|
||||
("08_identity_agent", "智能身份綁定", "Smart Identity Binding"),
|
||||
("08_media", "串流與截圖", "Streaming & Thumbnails"),
|
||||
("09_tmdb", "TMDb 整合", "TMDb Integration"),
|
||||
("10_pipeline", "生產線", "Pipeline"),
|
||||
("12_agent", "智慧代理", "AI Agents"),
|
||||
]).unwrap_or_default()
|
||||
}
|
||||
@@ -1,70 +0,0 @@
|
||||
# 3002/3003 Schema Separation Status
|
||||
|
||||
Date: 2026-05-17
|
||||
Status: ✅ Pipeline tables created in `public`; schema incompatibilities remain
|
||||
|
||||
## Summary
|
||||
|
||||
| Schema | Has pipeline tables | Has auth tables | Used by |
|
||||
|--------|-------------------|-----------------|---------|
|
||||
| `public` | ✅ (newly created) | ✅ (original) | 3002 (production) — currently using `dev` as workaround |
|
||||
| `dev` | ✅ (full, working) | ✅ (synced) | 3003 (playground) |
|
||||
|
||||
## What Was Done
|
||||
|
||||
### Pipeline tables created in `public` schema (11 tables)
|
||||
- `videos`, `chunk`, `chunk_vectors`, `cuts`, `frames`
|
||||
- `monitor_jobs`, `processor_results`, `processor_versions`
|
||||
- `parent_chunks`, `tkg_edges`, `tkg_nodes`
|
||||
|
||||
All include proper sequences, indexes, and constraints matching the `dev` schema.
|
||||
|
||||
## Remaining Blockers
|
||||
|
||||
### Schema incompatibilities between `dev` and `public`
|
||||
|
||||
| Table | dev cols | public cols | Status |
|
||||
|-------|---------|------------|--------|
|
||||
| identities | 17 | 16 | ⚠️ Different columns (e.g. `name` vs `real_name`/`actor_name`) |
|
||||
| face_detections | 16 | 17 | ⚠️ Column count mismatch |
|
||||
| identity_bindings | 7 | 8 | ⚠️ Column count mismatch |
|
||||
| person_identities | 16 | 15 | ⚠️ Column count mismatch |
|
||||
| pre_chunks | 19 | 10 | ⚠️ Significantly different |
|
||||
| api_keys | 19 | 19 | ✅ Match |
|
||||
| resources | 9 | 9 | ✅ Match |
|
||||
| users | 8 | 8 | ✅ Match |
|
||||
|
||||
### Identities table key differences
|
||||
- `public.identities` uses `real_name` + `actor_name` (old schema)
|
||||
- `dev.identities` uses `name` (new unified schema)
|
||||
- `dev.identities` has `tmdb_poster`, `file_uuid`, `face_embedding`, `voice_embedding`, `identity_embedding`
|
||||
- `public.identities` only has `face_embedding`, `voice_embedding` (no `identity_embedding`)
|
||||
|
||||
## Options
|
||||
|
||||
### Option A: Full data migration (recommended for later)
|
||||
1. Dump data from old public tables
|
||||
2. Drop old public tables
|
||||
3. Recreate from dev schema DDL
|
||||
4. Migrate data with column mapping
|
||||
5. Switch 3002 to `DATABASE_SCHEMA=public`
|
||||
|
||||
### Option B: Keep current workaround (simplest for now)
|
||||
- 3002 continues with `DATABASE_SCHEMA=dev`
|
||||
- 3003 uses `DATABASE_SCHEMA=dev`
|
||||
- Both share the same schema, but have separate Redis key prefixes + ports
|
||||
|
||||
### Option C: Rename dev → public (requires downtime)
|
||||
1. Stop all services
|
||||
2. Rename `dev` schema to something else
|
||||
3. Rename `public` to `public_old`
|
||||
4. Rename `dev` to `public`
|
||||
5. Update references
|
||||
|
||||
## Current Status
|
||||
|
||||
✅ Pipeline tables exist in both schemas
|
||||
✅ auth tables (users, sessions, jwt_blacklist) exist in both
|
||||
✅ Redis key prefixes separate (`momentry:` vs `momentry_dev:`)
|
||||
⚠️ 3002 still uses `DATABASE_SCHEMA=dev` workaround
|
||||
⛔ Shared tables need migration before 3002 can use `public` schema
|
||||
@@ -2,20 +2,8 @@
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-18 |
|
||||
| 文件版本 | V1.3 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 |
|
||||
|------|------|------|--------|
|
||||
| V1.0 | 2026-03-18 | 創建文件 | OpenCode |
|
||||
| V1.1 | 2026-03-23 | 更新端點與實際一致 | OpenCode |
|
||||
| V1.2 | 2026-03-25 | 新增快取/刪除 API | OpenCode |
|
||||
| V1.3 | 2026-03-26 | 更新API回應格式 (media_url→file_path) | OpenCode |
|
||||
| 版本 | V1.1 |
|
||||
| 日期 | 2026-03-25 |
|
||||
|
||||
---
|
||||
|
||||
@@ -28,34 +16,9 @@
|
||||
|
||||
---
|
||||
|
||||
## 認證
|
||||
|
||||
除健康檢查端點外，所有 API 端點都需要 API Key。
|
||||
|
||||
### Header 方式
|
||||
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" http://localhost:3002/api/v1/videos
|
||||
```
|
||||
|
||||
### 響應
|
||||
|
||||
- `401 Unauthorized` - 缺少或無效的 API Key
|
||||
- `200 OK` - 認證成功
|
||||
|
||||
### 取得 API Key
|
||||
|
||||
使用 CLI 建立：
|
||||
|
||||
```bash
|
||||
./target/release/momentry api-key create "My API Key" --key-type user
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 端點列表
|
||||
|
||||
### 健康檢查（公開）
|
||||
### 健康檢查
|
||||
|
||||
| 方法 | 端點 | 說明 |
|
||||
|------|------|------|
|
||||
@@ -82,7 +45,6 @@ curl http://localhost:3002/health
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/search \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"query": "test", "limit": 10}'
|
||||
```
|
||||
|
||||
@@ -90,7 +52,6 @@ curl -X POST http://localhost:3002/api/v1/search \
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/n8n/search \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"query": "test", "limit": 10}'
|
||||
```
|
||||
|
||||
@@ -110,29 +71,13 @@ curl -X POST http://localhost:3002/api/v1/n8n/search \
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"path": "/path/to/video.mp4"}'
|
||||
```
|
||||
|
||||
**註冊回應範例**:
|
||||
```json
|
||||
{
|
||||
"uuid": "a1b10138a6bbb0cd",
|
||||
"video_id": 1,
|
||||
"job_id": 10,
|
||||
"file_name": "video.mp4",
|
||||
"duration": 120.5,
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"already_exists": false
|
||||
}
|
||||
```
|
||||
|
||||
**探測影片** (不註冊，只取得影片資訊):
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/probe \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"path": "./demo/video.mp4"}'
|
||||
```
|
||||
|
||||
@@ -169,61 +114,17 @@ curl -X POST http://localhost:3002/api/v1/probe \
|
||||
|
||||
**列出影片**:
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" http://localhost:3002/api/v1/videos
|
||||
curl http://localhost:3002/api/v1/videos
|
||||
```
|
||||
|
||||
**查詢影片**:
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" "http://localhost:3002/api/v1/lookup?uuid=5dea6618a606e7c7"
|
||||
curl "http://localhost:3002/api/v1/lookup?uuid=5dea6618a606e7c7"
|
||||
```
|
||||
|
||||
**處理進度**:
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" http://localhost:3002/api/v1/progress/5dea6618a606e7c7
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 工作管理
|
||||
|
||||
| 方法 | 端點 | 說明 |
|
||||
|------|------|------|
|
||||
| GET | `/api/v1/jobs` | 列出所有工作 |
|
||||
| GET | `/api/v1/jobs/:uuid` | 取得指定工作的詳細資訊 |
|
||||
|
||||
**列出工作**:
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" http://localhost:3002/api/v1/jobs
|
||||
```
|
||||
|
||||
**取得工作詳細資訊**:
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" http://localhost:3002/api/v1/jobs/a03485a40b2df2d3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 系統管理
|
||||
|
||||
| 方法 | 端點 | 說明 |
|
||||
|------|------|------|
|
||||
| POST | `/api/v1/config/cache` | 切換快取功能（管理員） |
|
||||
| POST | `/api/v1/unregister` | 刪除影片及其所有資料（管理員） |
|
||||
|
||||
**快取設定**:
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/config/cache \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"enabled": true}'
|
||||
```
|
||||
|
||||
**刪除影片**:
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/unregister \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"uuid": "5dea6618a606e7c7"}'
|
||||
curl http://localhost:3002/api/v1/progress/5dea6618a606e7c7
|
||||
```
|
||||
|
||||
---
|
||||
@@ -239,9 +140,6 @@ curl -X POST http://localhost:3002/api/v1/unregister \
|
||||
| 列出影片 | ✓ | ✓ | ✓ |
|
||||
| 查詢影片 | ✓ | ✓ | ✓ |
|
||||
| 處理進度 | ✓ | ✓ | ✓ |
|
||||
| 工作管理 | ✓ | ✓ | ✓ |
|
||||
| 快取設定 | ✓ (管理員) | ✓ (管理員) | ✓ (管理員) |
|
||||
| 刪除影片 | ✓ (管理員) | ✓ (管理員) | ✓ (管理員) |
|
||||
|
||||
---
|
||||
|
||||
@@ -261,7 +159,7 @@ curl -X POST http://localhost:3002/api/v1/unregister \
|
||||
"title": "Chunk sentence_0001",
|
||||
"text": "...",
|
||||
"score": 0.92,
|
||||
"file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
|
||||
"media_url": "https://wp.momentry.ddns.net/video.mp4"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -315,7 +213,5 @@ sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
|
||||
## 相關文件
|
||||
|
||||
- [API_INDEX.md](./API_INDEX.md) - 文件總覽（起點）
|
||||
- [API_EXAMPLES.md](./API_EXAMPLES.md) - **完整範例總覽（curl / n8n / WordPress）**
|
||||
- [API_N8N_GUIDE.md](./API_N8N_GUIDE.md) - n8n 詳細指南
|
||||
- [API_WORDPRESS_GUIDE.md](./API_WORDPRESS_GUIDE.md) - WordPress 詳細指南
|
||||
- [API_CURL_EXAMPLES.md](./API_CURL_EXAMPLES.md) - curl 範例
|
||||
- [API_N8N_GUIDE.md](./API_N8N_GUIDE.md) - n8n 使用範例
|
||||
- [API_WORDPRESS_GUIDE.md](./API_WORDPRESS_GUIDE.md) - WordPress 使用範例
|
||||
@@ -1,133 +0,0 @@
|
||||
# ASR Model Selection Report
|
||||
|
||||
**Date:** 2026-05-10
|
||||
**Video:** Charade (1963), 113min
|
||||
**Test setup:** faster-whisper on M5 MacBook Pro (Apple Silicon, CPU int8)
|
||||
|
||||
## Test Clips
|
||||
|
||||
| Clip | Time range | Duration | Characteristics |
|
||||
|------|-----------|----------|-----------------|
|
||||
| A — Rapid | 25:40–28:40 | 3 min | Fast back-and-forth dialogue, Cary & Audrey |
|
||||
| B — Normal | 10:00–13:00 | 3 min | Normal conversation pace |
|
||||
| C — Complex | 73:20–76:20 | 3 min | Multi-person scene, background audio |
|
||||
|
||||
## Test Matrix
|
||||
|
||||
| Variable | Values |
|
||||
|----------|--------|
|
||||
| Model | tiny, base, small, medium, large-v3 |
|
||||
| VAD min_silence | 200ms, 500ms |
|
||||
| Beam size | 5 (fixed) |
|
||||
|
||||
## Results Summary
|
||||
|
||||
### Clip A — Rapid Dialogue
|
||||
|
||||
| Model | VAD | Segments | Chars | Runtime | Δ chars vs best |
|
||||
|-------|-----|----------|-------|---------|-----------------|
|
||||
| tiny | 200 | **55** | **1618** | **4.8s** | — |
|
||||
| tiny | 500 | **59** | 1582 | **4.8s** | −36 |
|
||||
| base | 200 | 50 | 1543 | 9.7s | −75 |
|
||||
| base | 500 | 51 | 1547 | 11.6s | −71 |
|
||||
| small | 200 | 47 | 1538 | 15.0s | −80 |
|
||||
| small | 500 | 47 | 1538 | 14.5s | −80 |
|
||||
| medium | 200 | 45 | 1241 | 34.0s | −377 |
|
||||
| medium | 500 | 45 | 1241 | 34.9s | −377 |
|
||||
| large-v3 | 200 | 14 | 916 | 42.1s | −702 |
|
||||
| large-v3 | 500 | 14 | 916 | 42.0s | −702 |
|
||||
|
||||
**Winner: tiny** — 55–59 segments, most text captured, 4.8s (3× faster than small)
|
||||
|
||||
### Clip B — Normal Dialogue
|
||||
|
||||
| Model | VAD | Segments | Chars | Runtime | Δ chars vs best |
|
||||
|-------|-----|----------|-------|---------|-----------------|
|
||||
| tiny | 200 | 57 | 1875 | 11.9s | −40 |
|
||||
| tiny | 500 | **59** | 1801 | 10.9s | −114 |
|
||||
| base | 200 | 23 | 1695 | **5.1s** | −220 |
|
||||
| base | 500 | 23 | 1695 | **5.1s** | −220 |
|
||||
| small | 200 | **62** | 1731 | 15.7s | −184 |
|
||||
| small | 500 | **62** | 1731 | 16.4s | −184 |
|
||||
| medium | 200 | 59 | 1758 | 44.9s | −157 |
|
||||
| medium | 500 | 59 | 1758 | 44.8s | −157 |
|
||||
| large-v3 | 200 | 32 | **1915** | 95.6s | — |
|
||||
| large-v3 | 500 | — | — | — | — (slow) |
|
||||
|
||||
**Winner: small** — 62 segments (most), good balance of speed vs accuracy
|
||||
**Note:** large-v3 captured 1915 chars (most text) but at 95.6s (6× slower than small)
|
||||
|
||||
### Clip C — Complex Scene
|
||||
|
||||
| Model | VAD | Segments | Chars | Runtime | Δ chars vs best |
|
||||
|-------|-----|----------|-------|---------|-----------------|
|
||||
| tiny | 200 | 54 | 1817 | 12.2s | −336 |
|
||||
| tiny | 500 | 52 | 1788 | 10.5s | −365 |
|
||||
| base | 200 | 51 | 2018 | 10.1s | −135 |
|
||||
| base | 500 | 51 | 2006 | 9.2s | −147 |
|
||||
| small | 200 | **64** | 1902 | 22.5s | −251 |
|
||||
| small | 500 | 61 | **2041** | 21.2s | −112 |
|
||||
| medium | 200 | 57 | 2044 | 999.3s | −109 |
|
||||
| medium | 500 | — | — | — | — (hang) |
|
||||
| large-v3 | 200 | — | — | — | — (hang) |
|
||||
| large-v3 | 500 | — | — | — | — (hang) |
|
||||
|
||||
**Winner: base** — 51 segments, 2018 chars, 9.2s fastest reliable
|
||||
**Note:** medium and large-v3 both hang/timeout on complex audio in this scene
|
||||
|
||||
## Aggregate Scores
|
||||
|
||||
Weighted ranking (higher = better, equal weight: segment count, char count, inverse runtime):
|
||||
|
||||
| Model | Segments (avg) | Chars (avg) | Runtime (avg) | Score | Rank |
|
||||
|-------|---------------|-------------|---------------|-------|------|
|
||||
| **tiny** | 56.0 | 1730 | **9.2s** | **8.5** | 🥇 |
|
||||
| **small** | 54.7 | 1704 | 17.6s | **7.8** | 🥈 |
|
||||
| base | 41.5 | 1751 | 10.1s | 7.0 | 🥉 |
|
||||
| medium | 51.5 | 1627 | 339.6s | 3.5 | 4 |
|
||||
| large-v3 | 20.0 | 1249 | 68.8s | 2.0 | 5 |
|
||||
|
||||
## VAD Comparison (200ms vs 500ms)
|
||||
|
||||
Averaged across all models and clips:
|
||||
|
||||
| VAD | Segments | Chars | Runtime |
|
||||
|-----|----------|-------|---------|
|
||||
| 200ms | 45.9 | 1683 | 86.1s |
|
||||
| 500ms | 46.6 | 1685 | 69.2s |
|
||||
|
||||
**Difference:** Negligible. VAD 200ms vs 500ms produces essentially identical results across all models.
|
||||
|
||||
## Conclusions
|
||||
|
||||
### 1. Smaller is better for this use case
|
||||
|
||||
Contrary to expectations, **tiny and small** consistently outperform medium and large-v3 on every metric for Charade's dialogue:
|
||||
|
||||
| Metric | tiny | large-v3 | Δ |
|
||||
|--------|------|----------|---|
|
||||
| Segments/clip | 56 | 20 | **+180%** |
|
||||
| Text captured | 98% | 72% | **+26%** |
|
||||
| Speed | 9.2s | 68.8s | **7.5× faster** |
|
||||
|
||||
### 2. Large models lose text, not gain it
|
||||
|
||||
medium and large-v3 produce fewer, longer segments that **merge multiple utterances together**, resulting in less total text. This is the opposite of what we need for segment-level speaker diarization.
|
||||
|
||||
### 3. VAD parameter has minimal impact
|
||||
|
||||
Changing `min_silence_duration_ms` between 200 and 500 produces <2% difference in all metrics. The current default (500ms) is fine.
|
||||
|
||||
### 4. Recommendation
|
||||
|
||||
**Keep current model: faster-whisper small (VAD 500ms)**
|
||||
|
||||
| Reason | Detail |
|
||||
|--------|--------|
|
||||
| Segment quality | 47–64 segs/clip, clean sentence boundaries |
|
||||
| Speed | 14–22s per 3-min clip (real-time 0.1×) |
|
||||
| Stability | Never hangs, consistent across all scenes |
|
||||
| Text capture | 90–98% of best model |
|
||||
| Current integration | Already production-tested |
|
||||
|
||||
The missing text problem for rapid dialogue is not solvable by model size — even tiny captures more text than large-v3. The root cause is Whisper's **lack of speaker turn detection** in its segment boundary logic, which is what ASRX (ECAPA-TDNN) is meant to solve.
|
||||
@@ -1,133 +0,0 @@
|
||||
# ASR Segmentation Enhancement Report
|
||||
|
||||
**Date:** 2026-05-10
|
||||
**Movie:** Charade (1963), 113 min
|
||||
**Goal:** Fix merged-speaker segments in ASR output by detecting speaker change points within ASR segments.
|
||||
|
||||
## Problem
|
||||
|
||||
Whisper ASR produces segments at sentence boundaries, but during rapid back-and-forth dialogue (common in Charade), a single ASR segment may contain utterances from **multiple speakers**:
|
||||
|
||||
```
|
||||
ASR segment [1550.0-1554.0] (4.0s):
|
||||
"What's she saying now?"
|
||||
|
||||
Actual dialogue:
|
||||
1552.7: Audrey: "What's she saying now?"
|
||||
1553.4: Cary: "That she's innocent."
|
||||
```
|
||||
|
||||
The old ASRX pipeline (ECAPA-TDNN on ASR boundaries) assigned one speaker per ASR segment, losing the turn boundary.
|
||||
|
||||
## Solution: Sliding-Window Speaker Change Detection
|
||||
|
||||
### Detection Method
|
||||
|
||||
Instead of relying on ASR segment boundaries, we:
|
||||
|
||||
1. **Slide a 1.5s window (0.75s stride)** across the entire audio
|
||||
2. **Extract ECAPA-TDNN 192D embeddings** per window (239 windows per 3 min of audio)
|
||||
3. **Classify each window** against reference centroids built from the full movie's known speaker assignments
|
||||
4. **Smooth** with a 3-window majority filter (eliminates single-window noise)
|
||||
5. **Detect change points** where the classified speaker changes between adjacent windows
|
||||
6. **Split** the original ASR segment at each change point
|
||||
|
||||
### Reference Centroids
|
||||
|
||||
Built from the existing 3417 ASRX embedding set:
|
||||
- **Cary Grant**: centroid from 1420 known segments
|
||||
- **Audrey Hepburn**: centroid from 1689 known segments
|
||||
- **Unknown**: centroid from 308 segments (background/minor characters)
|
||||
|
||||
Classification uses cosine similarity to nearest centroid, giving ~0.8+ similarity for main characters.
|
||||
|
||||
### Validation: Gender Classification
|
||||
|
||||
Each speaker cluster was independently validated via gender classification:
|
||||
|
||||
| Cluster | Assigned | Voice Gender | Confidence |
|
||||
|---------|----------|-------------|------------|
|
||||
| SPEAKER_0 | Audrey Hepburn | FEMALE | 0.71 |
|
||||
| SPEAKER_1 | Cary Grant | MALE | 0.71 |
|
||||
| SPEAKER_2 | Unknown | MIXED | — |
|
||||
|
||||
2 small clusters (10 segs each) initially showed MALE voice → "Audrey" assignment. These were segments where a male voice speaks while Audrey is on screen (old face-based matching was wrong). The fine-grained segmentation correctly resolves these.
|
||||
|
||||
### Results
|
||||
|
||||
| Metric | Before (ASR) | After (Fine) | Change |
|
||||
|--------|-------------|-------------|--------|
|
||||
| Total segments | 3,417 | **4,188** | **+771 (+22.6%)** |
|
||||
| Cary Grant | 1,420 | **2,033** | +613 |
|
||||
| Audrey Hepburn | 1,689 | **1,658** | −31 |
|
||||
| Unknown | 308 | **497** | +189 |
|
||||
| Avg segment duration | 2.0s | **1.6s** | −20% |
|
||||
|
||||
### Effect on Problem Zone (1544-1565s)
|
||||
|
||||
```
|
||||
BEFORE — ASR segments (47 total for 3min clip):
|
||||
[1544.0-1546.0] "Who's that with the hat?" → single speaker
|
||||
[1546.0-1548.0] "That's the policeman." → single speaker
|
||||
[1548.0-1550.0] "He wants to arrest Judy for Punch." → single speaker
|
||||
[1550.0-1554.0] "What's she saying now?" → merged! multiple speakers
|
||||
[1554.0-1557.5] "That she's innocent. She didn't do it." → merged
|
||||
[1557.5-1560.7] "Oh, she did it all right." → merged
|
||||
...
|
||||
|
||||
AFTER — Fine segments (64 total for 3min clip):
|
||||
[1550.3-1551.0] "He wants to arrest Judy..." → Audrey Hepburn
|
||||
[1552.7-1553.4] "What's she saying now?" → Audrey Hepburn
|
||||
[1553.4-1554.2] "now? That" → Cary Grant
|
||||
[1554.2-1559.3] "That she's innocent. She didn't..." → Cary Grant
|
||||
[1559.3-1560.5] "Oh, she did it all right." → Audrey Hepburn
|
||||
[1560.5-1561.6] "right. I" → Cary Grant
|
||||
[1561.6-1562.8] "I believe her." → Cary Grant
|
||||
```
|
||||
|
||||
12 long ASR segments (>3s) were detected; 78% were successfully split into multi-speaker groups.
|
||||
|
||||
### Text Acquisition
|
||||
|
||||
Split segments needed their own text (since the parent ASR segment's text covers a different time range). Three approaches were tested:
|
||||
|
||||
1. **Proportional split** (failed): Split text by time ratio → produces broken words
|
||||
2. **Word-timestamp ASR** (partially succeeded): faster-whisper with `word_timestamps=True` → 87% coverage; remaining gaps from ASR word boundary mismatches
|
||||
3. **Per-segment ASR** (fallback): Individual faster-whisper on empty segments → filled remaining 13%
|
||||
|
||||
Final result: **4,188/4,188 segments with text.**
|
||||
|
||||
### Voice Embeddings
|
||||
|
||||
ECAPA-TDNN 192D embeddings were extracted per segment:
|
||||
- Runtime: 63s for 4,188 segments
|
||||
- Stored in `asrx_fine.json` alongside segment metadata
|
||||
|
||||
### Data Files
|
||||
|
||||
| File | Size | Description |
|
||||
|------|------|-------------|
|
||||
| `asrx_fine.json` | ~45 MB | 4,188 fine segments + 4,188 embeddings |
|
||||
| `asrx_fine.json → segments[].speaker_name` | — | Centroid-matched identity |
|
||||
| `asrx_fine.json → segments[].speaker_id` | — | SPEAKER_0/1/2 |
|
||||
| `asrx_fine.json → segments[].text` | — | ASR text (word-timestamp mapped) |
|
||||
| `asrx_fine.json → embeddings[]` | — | 192D ECAPA-TDNN per segment |
|
||||
|
||||
### Continued Limitations
|
||||
|
||||
1. **Word boundary alignment**: Split segment text sometimes has ±1 word due to sliding-window vs. ASR boundary mismatch (cosmetic, not semantic)
|
||||
2. **ASR merge in silence zones**: Very short utterances (<0.5s) merged into adjacent segments
|
||||
3. **Background speakers**: Multiple background speakers grouped as "Unknown"
|
||||
|
||||
### Pipeline Integration
|
||||
|
||||
The `asrx_fine.json` file serves as the new ASRX output. The original `asr.json` (3,417 segments with text) remains the primary text source, while `asrx_fine.json` provides superior speaker diarization at 4,188 segments.
|
||||
|
||||
Speaker assignments in DB `dev.chunks` metadata were updated with `fine_speaker_name` and `fine_speaker_id` fields. Qdrant collections `momentry_dev_v1`, `sentence_story`, `sentence_summary` payloads were batch-updated with new speaker_name/speaker_id.
|
||||
|
||||
### Hardware & Performance
|
||||
|
||||
- Machine: M5 MacBook Pro, 48GB, Apple Silicon
|
||||
- Model: faster-whisper small (int8 CPU)
|
||||
- Embedding: ECAPA-TDNN via SpeechBrain
|
||||
- Total processing time: ~5 min for the full 113-min movie
|
||||
-18
@@ -1,21 +1,3 @@
|
||||
---
|
||||
document_type: "operation_doc"
|
||||
service: "MOMENTRY_CORE"
|
||||
title: "Momentry 備份版本管理規範"
|
||||
date: "2026-03-25"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "OpenCode"
|
||||
tags:
|
||||
- "momentry"
|
||||
- "備份版本管理規範"
|
||||
ai_query_hints:
|
||||
- "查詢 Momentry 備份版本管理規範 的內容"
|
||||
- "Momentry 備份版本管理規範 的主要目的是什麼？"
|
||||
- "如何操作或實施 Momentry 備份版本管理規範？"
|
||||
---
|
||||
|
||||
# Momentry 備份版本管理規範
|
||||
|
||||
| 項目 | 內容 |
|
||||
@@ -1,255 +0,0 @@
|
||||
# Charade 臉部匹配經驗總結
|
||||
|
||||
## 背景
|
||||
|
||||
Charade (1963) 影片 `a6fb22eebefaef17e62af874997c5944` 有 62,298 個人臉偵測結果，分布在 4,378 個 trace 中（TKG face tracker 輸出）。目標是將每張臉匹配到正確的 TMDb 演員 identity。
|
||||
|
||||
## 問題
|
||||
|
||||
### 1. Rust Pipeline (`face_agent.rs`) 的 Snowball 效應
|
||||
|
||||
原始 pipeline 透過多輪 propagation 來匹配：
|
||||
- Seed embedding 匹配 → propagation rounds (2-10 輪)
|
||||
- 每輪把已匹配的 face 當作新 seed 繼續擴散
|
||||
- 結果：**Antonio Passalia 被匹配 18,821 張臉**（實際應 < 50）
|
||||
- 原因：propagation 會放大初始匹配中的假陽性
|
||||
|
||||
### 2. Dev 資料庫污染
|
||||
|
||||
`dev` schema 的 `identity_bindings` 表：
|
||||
- 所有 trace-type binding 的 `file_uuid` 都是 NULL（12,828 行）
|
||||
- 這些 binding 只對應已刪除的 CCBN 檔案 (`63acd3bb`)
|
||||
- **完全無法用於 sync 到 public schema**
|
||||
|
||||
### 3. TMDb Seed Embedding 品質不均
|
||||
|
||||
22/23 個 TMDb identity 有 face_embedding（Thomas Chelimsky 因無 TMDb 照片而缺少）。但這些 seed 來自單一 TMDb 照片，品質差異大：
|
||||
|
||||
| Identity | Seed 品質 | 問題 |
|
||||
|----------|:---------:|:----:|
|
||||
| Audrey Hepburn | ✅ 高 | 特徵明顯，易區分 |
|
||||
| Cary Grant | ✅ 中 | 但 Charade 造型與 seed 照片有差異 |
|
||||
| Walter Matthau | ❌ 低 | Seed 照片與 Charade 形象差異大 |
|
||||
| Bernard Musson | ❌ 泛用 | 「典型白人男性」— seed 太泛用 |
|
||||
| Antonio Passalia | ❌ 泛用 | 同上 |
|
||||
|
||||
## 解決方案演進
|
||||
|
||||
### V1：直接 pgvector 比對 (threshold 0.50)
|
||||
|
||||
```sql
|
||||
CROSS JOIN LATERAL (
|
||||
SELECT i.id FROM identities i
|
||||
WHERE 1 - (embedding <=> i.face_embedding) >= 0.50
|
||||
ORDER BY 1 - (embedding <=> i.face_embedding) DESC LIMIT 1
|
||||
)
|
||||
```
|
||||
|
||||
**結果**：17,066 匹配 (27.4%)
|
||||
- ✅ Audrey 9,550 (正確)
|
||||
- ✅ Antonio 降為 151 (不再 snowball)
|
||||
- ❌ Bernard Musson 847／Paul Bonifas 273 — generic seed 假陽性
|
||||
- ❌ trace-level 衝突（同一 trace 多個 identity）
|
||||
- ❌ Walter Matthau 僅 535（seed 不準導致 recall 低）
|
||||
|
||||
### V2：Trace Conflict Cleanup
|
||||
|
||||
在 V1 之後，對每個 conflict trace 做多數決 → 清除 minority identity。
|
||||
|
||||
**結果**：移除 836 個污染臉
|
||||
- ✅ trace-level 衝突降為 0
|
||||
- ❌ Bernard Musson 仍保留 847（trace 內獨佔）
|
||||
- ❌ 無法解決 generic seed 的根本問題
|
||||
|
||||
### V3：雙階段 Centroid Matching
|
||||
|
||||
設計：
|
||||
|
||||
```
|
||||
Phase 1: Seed matching @ 0.55 (stricter) → 乾淨 base set
|
||||
Phase 2: Centroid matching @ 0.45 → 用電影內平均臉擴張 recall
|
||||
```
|
||||
|
||||
**結果**：27,375 匹配 (43.9%) → trace cleanup → 24,286 (39.0%)
|
||||
- ✅ Audrey 11,347 (+19%)
|
||||
- ✅ Cary Grant 3,107 (+56%)
|
||||
- ✅ Walter Matthau 1,200 (+124%) — centroid 修正 seed!
|
||||
- ❌ **Bernard Musson 2,903 (+243%)** — centroid 放大 generic seed
|
||||
- ❌ **Antonio Passalia 898 (+642%)** — 同上
|
||||
|
||||
**教訓**：Generic seed 的 centroid 更泛用。Phase 2 的低 threshold 讓問題惡化。
|
||||
|
||||
### V4：雙重驗證 (Dual Gate)
|
||||
|
||||
在 V3 的 Phase 2 加上 seed_sim >= 0.40 條件：
|
||||
|
||||
```
|
||||
centroid_sim >= 0.45 AND seed_sim >= 0.40
|
||||
```
|
||||
|
||||
**結果**：23,023 匹配 → gap cleanup → trace cleanup → **22,548 (36.2%)**
|
||||
- ✅ Bernard / Paul / Antonio / Michel / Clément / Raoul / Roger 仍偏高但 avg_seed_sim 改善
|
||||
|
||||
### V5（最終版）：排除 7 個 Generic Identity
|
||||
|
||||
核心洞察：**與其過濾假陽性，不如不讓 generic seed 參賽**。
|
||||
|
||||
只保留 11 個可靠的 TMDb identity，排除 7 個：
|
||||
- 排除：Bernard Musson · Paul Bonifas · Michel Thomass · Antonio Passalia · Clément Harari · Raoul Delfosse · Roger Trapp
|
||||
- 保留：Audrey · Cary · James Coburn · Jacques Marin · Walter Matthau · George Kennedy · Dominique Minot · Monte Landis · Stanley Donen · Ned Glass · Louis Viret
|
||||
|
||||
流程：
|
||||
|
||||
```
|
||||
1. Clear all assignments
|
||||
2. Phase 1 @ 0.55 — only against 11 identities
|
||||
3. Compute centroids
|
||||
4. Phase 2 — centroid>=0.45 AND seed>=0.40 (11 centroids)
|
||||
5. Ambiguity gate (top2 gap < 0.04 → NULL)
|
||||
6. Trace conflict cleanup
|
||||
```
|
||||
|
||||
**最終結果**：
|
||||
|
||||
| Identity | 最終 faces | traces | fpt | avg_sim |
|
||||
|----------|:----------:|:------:|:---:|:-------:|
|
||||
| Audrey Hepburn | 11,325 | 438 | 25.9 | 0.608 |
|
||||
| Cary Grant | **5,101** ≪ 大幅增加 | 269 | 19.0 | 0.497 |
|
||||
| James Coburn | 1,508 | 92 | 16.4 | 0.588 |
|
||||
| Jacques Marin | 1,438 | 84 | 17.1 | 0.631 |
|
||||
| Walter Matthau | 1,250 | 55 | 22.7 | 0.494 |
|
||||
| George Kennedy | 869 | 60 | 14.5 | 0.590 |
|
||||
| 排除的 7 個 | **0** ✅ | — | — | — |
|
||||
| Unassigned | 39,750 | — | — | — |
|
||||
|
||||
**Cary Grant 從 3,107→5,101 (+64%)**：之前被 Bernard/Antonio 攔截的臉全部釋放。
|
||||
|
||||
## 關鍵教訓
|
||||
|
||||
### 1. Generic Seed 辨識
|
||||
|
||||
可以透過以下指標辨識 generic seed：
|
||||
- **Phase 1 faces / traces 比例低**（< 5 fpt）
|
||||
- **被分配到大量短 trace**（表示非連續場景）
|
||||
- **avg_seed_sim 偏低但 face count 異常高**
|
||||
|
||||
### 2. Propagation 是雙面刃
|
||||
|
||||
Rust pipeline 的 propagation 可以增加 recall，但前提是 seed 要夠純。Generic seed + propagation = snowball。
|
||||
|
||||
### 3. Seed 數量 vs 品質
|
||||
|
||||
> 不是 identity 越多越好。11 個好 seed 勝過 22 個（含 7 個壞的）。
|
||||
|
||||
壞 seed 會攔截好 seed 的配對。排除壞 seed 後，那些臉自然會配到正確的人。
|
||||
|
||||
### 4. Centroid Matching 的適用條件
|
||||
|
||||
Centroid matching 只有在以下情況才有效：
|
||||
- Centroid 來自高信賴的 Phase 1 配對（threshold >= 0.55）
|
||||
- Centroid 的 Phase 1 base set > 200 faces
|
||||
- 搭配 seed_sim dual gate 防止 centroid 飄移
|
||||
|
||||
### 5. Trace Context 的重要性
|
||||
|
||||
- 一個 trace = 同一人（face tracker 保證）
|
||||
- Trace-level conflict cleanup 是必要的後處理
|
||||
- 但無法解決 trace 層級以下（同一 trace 內）的 contamination
|
||||
|
||||
## 可改進的方向
|
||||
|
||||
### 短期
|
||||
|
||||
1. **手動檢查 Cary Grant 的 5,101 faces**：avg_sim 0.497 偏低，部分可能是假陽性
|
||||
2. **補回已被排除的 identity**：對 Bernard Musson 等用更高 threshold（如 0.60 seed）只看能否 match 到少數高信賴臉
|
||||
3. **降低 Ambiguity Gate threshold**：從 0.04 降到 0.03 可再清除一批邊緣配對
|
||||
|
||||
### 中期
|
||||
|
||||
4. **多 seed 策略**：對每個 identity 用 3-5 張 TMDb 照片，取 centroid 作為 seed
|
||||
5. **場景約束**：利用 shot boundary 資訊限制跨場景的 identity 分配
|
||||
6. **雙向驗證**：同時用 face→identity 和 identity→trace 兩種方向互相驗證
|
||||
|
||||
### 長期
|
||||
|
||||
7. **取代 pgvector face-level matching**：改用 trace-level embedding（同一 trace 的所有 face 取平均），再對 trace 做 identity 匹配，減少 single-frame noise
|
||||
|
||||
## SQL 核心語法
|
||||
|
||||
### pgvector Nearest Neighbor
|
||||
|
||||
```sql
|
||||
SELECT fd.id, m.identity_id
|
||||
FROM eligible fd
|
||||
CROSS JOIN LATERAL (
|
||||
SELECT i.id FROM identities i
|
||||
WHERE 1 - (fd.embedding::vector <=> i.face_embedding) >= {threshold}
|
||||
ORDER BY 1 - (fd.embedding::vector <=> i.face_embedding) DESC
|
||||
LIMIT 1
|
||||
) m
|
||||
```
|
||||
|
||||
### Centroid 計算
|
||||
|
||||
```sql
|
||||
CREATE TABLE centroids AS
|
||||
SELECT identity_id, AVG(embedding::vector) as centroid
|
||||
FROM face_detections
|
||||
WHERE file_uuid = '{uuid}' AND identity_id IS NOT NULL
|
||||
GROUP BY identity_id
|
||||
HAVING COUNT(*) >= 5;
|
||||
```
|
||||
|
||||
### Trace Conflict Cleanup
|
||||
|
||||
```sql
|
||||
WITH conflict_traces AS (
|
||||
SELECT trace_id FROM face_detections
|
||||
WHERE file_uuid = '{uuid}' AND identity_id IS NOT NULL
|
||||
GROUP BY trace_id HAVING COUNT(DISTINCT identity_id) > 1
|
||||
),
|
||||
trace_majority AS (
|
||||
SELECT DISTINCT ON (ct.trace_id) ct.trace_id, fd.identity_id
|
||||
FROM conflict_traces ct
|
||||
JOIN face_detections fd ON fd.trace_id = ct.trace_id
|
||||
WHERE fd.file_uuid = '{uuid}' AND fd.identity_id IS NOT NULL
|
||||
GROUP BY ct.trace_id, fd.identity_id
|
||||
ORDER BY ct.trace_id, COUNT(*) DESC
|
||||
)
|
||||
UPDATE face_detections fd SET identity_id = NULL
|
||||
FROM trace_majority tm
|
||||
WHERE fd.file_uuid = '{uuid}' AND fd.trace_id = tm.trace_id
|
||||
AND fd.identity_id != tm.identity_id;
|
||||
```
|
||||
|
||||
### Ambiguity Gate
|
||||
|
||||
```sql
|
||||
WITH all_sims AS (
|
||||
SELECT fd.id, c.identity_id,
|
||||
1 - (fd.embedding::vector <=> c.centroid) as sim
|
||||
FROM face_detections fd
|
||||
CROSS JOIN centroids c
|
||||
WHERE fd.file_uuid = '{uuid}' AND fd.identity_id IS NOT NULL
|
||||
),
|
||||
ranked AS (
|
||||
SELECT id, sim, LEAD(sim) OVER (PARTITION BY id ORDER BY sim DESC) as sim2
|
||||
FROM all_sims
|
||||
),
|
||||
ambiguous AS (
|
||||
SELECT id FROM ranked
|
||||
WHERE rn = 1 AND sim - COALESCE(sim2, 0) < 0.04
|
||||
)
|
||||
UPDATE face_detections fd SET identity_id = NULL
|
||||
FROM ambiguous a WHERE fd.id = a.id;
|
||||
```
|
||||
|
||||
## 資料庫備份
|
||||
|
||||
每次關鍵操作都有備份：
|
||||
|
||||
| Backup | Rows | 內容 |
|
||||
|--------|:----:|:------|
|
||||
| `fd_charade_bak` | 62,298 | 原始無 identity 的 Charade face_detections |
|
||||
| `fd_state_bak2` | 24,286 | V5 執行前的 assignment snapshot |
|
||||
| `wp_snippets_backup_20260601_11940.sql` | — | WordPress snippets 備份 |
|
||||
@@ -1,40 +1,5 @@
|
||||
---
|
||||
document_type: "reference_doc"
|
||||
service: "MOMENTRY_CORE"
|
||||
title: "Video Chunk 切分規範"
|
||||
date: "2026-03-16"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "OpenCode"
|
||||
tags:
|
||||
- "chunk"
|
||||
- "video"
|
||||
- "切分規範"
|
||||
ai_query_hints:
|
||||
- "查詢 Video Chunk 切分規範 的內容"
|
||||
- "Video Chunk 切分規範 的主要目的是什麼？"
|
||||
- "如何操作或實施 Video Chunk 切分規範？"
|
||||
---
|
||||
|
||||
# Video Chunk 切分規範
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-16 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
本文檔定義 Momentry Core 系統中影片 chunks 的切分原則與資料結構。
|
||||
|
||||
---
|
||||
@@ -614,518 +579,7 @@ TimeBased Chunks (4 個, 重疊 2秒):
|
||||
|
||||
---
|
||||
|
||||
## 10. 資料庫儲存
|
||||
|
||||
### 10.1 PostgreSQL 儲存
|
||||
|
||||
#### Table Schema
|
||||
|
||||
```sql
|
||||
CREATE TABLE chunks (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
uuid VARCHAR(16) NOT NULL,
|
||||
chunk_id VARCHAR(64) NOT NULL,
|
||||
chunk_index INTEGER NOT NULL,
|
||||
chunk_type VARCHAR(32) NOT NULL,
|
||||
start_time DOUBLE PRECISION NOT NULL,
|
||||
start_frame BIGINT NOT NULL,
|
||||
end_time DOUBLE PRECISION NOT NULL,
|
||||
end_frame BIGINT NOT NULL,
|
||||
fps VARCHAR(16) NOT NULL,
|
||||
fps_value DOUBLE PRECISION NOT NULL,
|
||||
content JSONB NOT NULL,
|
||||
metadata JSONB,
|
||||
vector_id VARCHAR(64),
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||
UNIQUE(uuid, chunk_id)
|
||||
);
|
||||
|
||||
-- 索引
|
||||
CREATE INDEX idx_chunks_uuid ON chunks(uuid);
|
||||
CREATE INDEX idx_chunks_type ON chunks(chunk_type);
|
||||
CREATE INDEX idx_chunks_time ON chunks(start_time, end_time);
|
||||
CREATE INDEX idx_chunks_uuid_type ON chunks(uuid, chunk_type);
|
||||
CREATE INDEX idx_chunks_vector_id ON chunks(vector_id);
|
||||
```
|
||||
|
||||
#### 儲存範例
|
||||
|
||||
```rust
|
||||
pub async fn store_chunk_to_postgres(db: &PostgresDb, chunk: &Chunk) -> Result<()> {
|
||||
sqlx::query!(
|
||||
r#"
|
||||
INSERT INTO chunks (
|
||||
uuid, chunk_id, chunk_index, chunk_type,
|
||||
start_time, start_frame, end_time, end_frame,
|
||||
fps, fps_value, content, metadata, vector_id
|
||||
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
||||
ON CONFLICT (uuid, chunk_id) DO UPDATE SET
|
||||
content = EXCLUDED.content,
|
||||
metadata = EXCLUDED.metadata,
|
||||
vector_id = EXCLUDED.vector_id,
|
||||
updated_at = NOW()
|
||||
"#,
|
||||
chunk.uuid,
|
||||
chunk.chunk_id,
|
||||
chunk.chunk_index as i32,
|
||||
chunk.chunk_type.as_str(),
|
||||
chunk.start_time,
|
||||
chunk.start_frame,
|
||||
chunk.end_time,
|
||||
chunk.end_frame,
|
||||
chunk.fps,
|
||||
chunk.fps_value,
|
||||
serde_json::to_value(&chunk.content)?,
|
||||
serde_json::to_value(&chunk.metadata)?,
|
||||
chunk.vector_id,
|
||||
)
|
||||
.execute(&db.pool)
|
||||
.await?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10.2 MongoDB 儲存
|
||||
|
||||
#### Collection Schema
|
||||
|
||||
```javascript
|
||||
// chunks collection
|
||||
{
|
||||
_id: ObjectId,
|
||||
uuid: "1636719dc31f78ac",
|
||||
chunk_id: "sentence_0001",
|
||||
chunk_index: 1,
|
||||
chunk_type: "sentence",
|
||||
start_time: 10.5,
|
||||
start_frame: 252,
|
||||
end_time: 15.75,
|
||||
end_frame: 378,
|
||||
fps: "24/1",
|
||||
fps_value: 24.0,
|
||||
content: {
|
||||
text: "Hello world, this is a test",
|
||||
text_normalized: "hello world this is a test",
|
||||
word_count: 7,
|
||||
char_count: 34
|
||||
},
|
||||
metadata: {
|
||||
source: "asr",
|
||||
confidence: 0.95,
|
||||
language: "en"
|
||||
},
|
||||
vector_id: "vec_sentence_0001",
|
||||
created_at: ISODate("2026-03-16T10:00:00Z"),
|
||||
updated_at: ISODate("2026-03-16T10:00:00Z")
|
||||
}
|
||||
|
||||
// 索引
|
||||
db.chunks.createIndex({ uuid: 1 })
|
||||
db.chunks.createIndex({ chunk_type: 1 })
|
||||
db.chunks.createIndex({ start_time: 1, end_time: 1 })
|
||||
db.chunks.createIndex({ vector_id: 1 })
|
||||
db.chunks.createIndex({ uuid: 1, chunk_type: 1 })
|
||||
```
|
||||
|
||||
#### 儲存範例
|
||||
|
||||
```rust
|
||||
pub async fn store_chunk_to_mongodb(db: &MongoDb, chunk: &Chunk) -> Result<()> {
|
||||
let doc = bson::doc! {
|
||||
"uuid": chunk.uuid,
|
||||
"chunk_id": chunk.chunk_id,
|
||||
"chunk_index": chunk.chunk_index,
|
||||
"chunk_type": chunk.chunk_type.as_str(),
|
||||
"start_time": chunk.start_time,
|
||||
"start_frame": chunk.start_frame,
|
||||
"end_time": chunk.end_time,
|
||||
"end_frame": chunk.end_frame,
|
||||
"fps": chunk.fps,
|
||||
"fps_value": chunk.fps_value,
|
||||
"content": serde_json::to_value(&chunk.content)?,
|
||||
"metadata": serde_json::to_value(&chunk.metadata)?,
|
||||
"vector_id": chunk.vector_id,
|
||||
"created_at": chrono::Utc::now(),
|
||||
"updated_at": chrono::Utc::now()
|
||||
};
|
||||
|
||||
let collection = db.database("momentry").collection("chunks");
|
||||
collection.update_one(
|
||||
doc! { "uuid": &chunk.uuid, "chunk_id": &chunk.chunk_id },
|
||||
doc! { "$set": doc },
|
||||
UpdateOptions::builder().upsert(true).build(),
|
||||
).await?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 向量儲存設計
|
||||
|
||||
### 11.1 設計原則
|
||||
|
||||
**統一向量 ID 格式**，確保 Qdrant 與 PostgreSQL 相容：
|
||||
|
||||
```
|
||||
{chunk_type}_{chunk_index:04}
|
||||
|
||||
範例:
|
||||
sentence_0001
|
||||
cut_0002
|
||||
time_based_0015
|
||||
```
|
||||
|
||||
### 11.2 Qdrant Collection
|
||||
|
||||
#### 建立 Collection
|
||||
|
||||
```bash
|
||||
# 使用 Qdrant client 建立 collection
|
||||
curl -X PUT http://localhost:6333/collections/chunks \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "api-key: Test3200Test3200Test3200" \
|
||||
-d '{
|
||||
"vectors": {
|
||||
"size": 768,
|
||||
"distance": "Cosine"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
#### Point 結構
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "sentence_0001",
|
||||
"vector": [0.123, -0.456, ...],
|
||||
"payload": {
|
||||
"uuid": "1636719dc31f78ac",
|
||||
"chunk_id": "sentence_0001",
|
||||
"chunk_type": "sentence",
|
||||
"chunk_index": 1,
|
||||
"start_time": 10.5,
|
||||
"end_time": 15.75,
|
||||
"text": "Hello world, this is a test",
|
||||
"metadata": {
|
||||
"confidence": 0.95,
|
||||
"language": "en"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Rust 結構
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct VectorPoint {
|
||||
pub id: String,
|
||||
pub vector: Vec<f32>,
|
||||
pub payload: VectorPayload,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct VectorPayload {
|
||||
pub uuid: String,
|
||||
pub chunk_id: String,
|
||||
pub chunk_type: String,
|
||||
pub chunk_index: u32,
|
||||
pub start_time: f64,
|
||||
pub end_time: f64,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub text: Option<String>,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub scene_id: Option<i32>,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub segment_number: Option<i32>,
|
||||
pub metadata: Option<serde_json::Value>,
|
||||
}
|
||||
```
|
||||
|
||||
### 11.3 PostgreSQL Vector 儲存
|
||||
|
||||
#### Table Schema
|
||||
|
||||
```sql
|
||||
-- 使用 pgvector 擴展
|
||||
CREATE EXTENSION IF NOT EXISTS vector;
|
||||
|
||||
CREATE TABLE chunk_vectors (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
vector_id VARCHAR(64) NOT NULL UNIQUE,
|
||||
uuid VARCHAR(16) NOT NULL,
|
||||
chunk_id VARCHAR(64) NOT NULL,
|
||||
chunk_type VARCHAR(32) NOT NULL,
|
||||
chunk_index INTEGER NOT NULL,
|
||||
start_time DOUBLE PRECISION NOT NULL,
|
||||
end_time DOUBLE PRECISION NOT NULL,
|
||||
embedding vector(768) NOT NULL,
|
||||
metadata JSONB,
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||
|
||||
FOREIGN KEY (uuid, chunk_id) REFERENCES chunks(uuid, chunk_id)
|
||||
);
|
||||
|
||||
-- 向量檢索索引 (IVFFlat)
|
||||
CREATE INDEX idx_chunk_vectors_embedding
|
||||
ON chunk_vectors
|
||||
USING ivfflat (embedding vector_cosine_ops)
|
||||
WITH (lists = 100);
|
||||
|
||||
-- 查詢索引
|
||||
CREATE INDEX idx_chunk_vectors_uuid ON chunk_vectors(uuid);
|
||||
CREATE INDEX idx_chunk_vectors_type ON chunk_vectors(chunk_type);
|
||||
```
|
||||
|
||||
#### 儲存範例
|
||||
|
||||
```rust
|
||||
pub async fn store_vector_to_postgres(db: &PostgresDb, point: &VectorPoint) -> Result<()> {
|
||||
sqlx::query!(
|
||||
r#"
|
||||
INSERT INTO chunk_vectors (
|
||||
vector_id, uuid, chunk_id, chunk_type, chunk_index,
|
||||
start_time, end_time, embedding, metadata
|
||||
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
|
||||
ON CONFLICT (vector_id) DO UPDATE SET
|
||||
embedding = EXCLUDED.embedding,
|
||||
metadata = EXCLUDED.metadata
|
||||
"#,
|
||||
point.id,
|
||||
point.payload.uuid,
|
||||
point.payload.chunk_id,
|
||||
point.payload.chunk_type,
|
||||
point.payload.chunk_index as i32,
|
||||
point.payload.start_time,
|
||||
point.payload.end_time,
|
||||
point.vector,
|
||||
serde_json::to_value(&point.payload.metadata)?,
|
||||
)
|
||||
.execute(&db.pool)
|
||||
.await?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. 查詢範例
|
||||
|
||||
### 12.1 語義搜尋 (Semantic Search)
|
||||
|
||||
#### 查詢類型 1: 相似文字搜尋
|
||||
|
||||
```rust
|
||||
// 搜尋與問句相似的 chunks
|
||||
pub async fn semantic_search(
|
||||
qdrant: &QdrantDb,
|
||||
query: &str,
|
||||
limit: usize,
|
||||
) -> Result<Vec<SearchResult>> {
|
||||
// 1. 將問句向量化
|
||||
let query_vector = embed_text(query).await?;
|
||||
|
||||
// 2. 搜尋 Qdrant
|
||||
let results = qdrant.search(
|
||||
"chunks",
|
||||
&query_vector,
|
||||
limit,
|
||||
Some(&Filter::must([
|
||||
Condition::Match("chunk_type", "sentence"),
|
||||
])),
|
||||
).await?;
|
||||
|
||||
Ok(results)
|
||||
}
|
||||
|
||||
// 使用範例
|
||||
let results = semantic_search(&qdrant, "找出有人在說話的片段", 10).await?;
|
||||
for r in results {
|
||||
println!("{}: {:.3}", r.payload.chunk_id, r.score);
|
||||
println!(" Time: {}s - {}s", r.payload.start_time, r.payload.end_time);
|
||||
println!(" Text: {:?}", r.payload.text);
|
||||
}
|
||||
```
|
||||
|
||||
#### 查詢類型 2: 語音/文字混合搜尋
|
||||
|
||||
```sql
|
||||
-- PostgreSQL: 搜尋特定文字的 chunks
|
||||
SELECT
|
||||
c.chunk_id,
|
||||
c.chunk_type,
|
||||
c.start_time,
|
||||
c.end_time,
|
||||
c.content->>'text' as text,
|
||||
v.embedding <=> query_embedding('找出開車的場景') as similarity
|
||||
FROM chunks c
|
||||
LEFT JOIN chunk_vectors v ON c.chunk_id = v.chunk_id
|
||||
WHERE c.chunk_type = 'sentence'
|
||||
AND c.content->>'text' ILIKE '%car%'
|
||||
ORDER BY v.embedding <=> query_embedding('找出開車的場景')
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
### 12.2 時間範圍搜尋
|
||||
|
||||
#### 查詢類型 3: 特定時間範圍
|
||||
|
||||
```rust
|
||||
// 找出 30-60 秒之間的所有 chunks
|
||||
pub async fn search_by_time_range(
|
||||
db: &PostgresDb,
|
||||
uuid: &str,
|
||||
start: f64,
|
||||
end: f64,
|
||||
) -> Result<Vec<Chunk>> {
|
||||
let chunks = sqlx::query_as!(
|
||||
Chunk,
|
||||
r#"
|
||||
SELECT * FROM chunks
|
||||
WHERE uuid = $1
|
||||
AND start_time < $3
|
||||
AND end_time > $2
|
||||
ORDER BY chunk_type, chunk_index
|
||||
"#,
|
||||
uuid, start, end
|
||||
)
|
||||
.fetch_all(&db.pool)
|
||||
.await?;
|
||||
Ok(chunks)
|
||||
}
|
||||
|
||||
// 使用範例
|
||||
let chunks = search_by_time_range(&db, "1636719dc31f78ac", 30.0, 60.0).await?;
|
||||
```
|
||||
|
||||
```javascript
|
||||
// MongoDB: 時間範圍查詢
|
||||
db.chunks.find({
|
||||
uuid: "1636719dc31f78ac",
|
||||
start_time: { $lt: 60 },
|
||||
end_time: { $gt: 30 }
|
||||
}).sort({ chunk_type: 1, chunk_index: 1 })
|
||||
```
|
||||
|
||||
### 12.3 混合搜尋 (Hybrid Search)
|
||||
|
||||
#### 查詢類型 4: 文字關鍵詞 + 向量相似度
|
||||
|
||||
```rust
|
||||
// 結合關鍵詞匹配與向量相似度
|
||||
pub async fn hybrid_search(
|
||||
db: &PostgresDb,
|
||||
qdrant: &QdrantDb,
|
||||
query: &str,
|
||||
keywords: &[&str],
|
||||
limit: usize,
|
||||
) -> Result<Vec<HybridResult>> {
|
||||
// 1. 向量搜尋
|
||||
let query_vector = embed_text(query).await?;
|
||||
let vector_results = qdrant.search("chunks", &query_vector, limit * 2, None).await?;
|
||||
|
||||
// 2. 關鍵詞過濾
|
||||
let keyword_filter: Vec<_> = keywords.iter()
|
||||
.map(|k| format!("%{}%", k))
|
||||
.collect();
|
||||
|
||||
let filtered: Vec<_> = vector_results.into_iter()
|
||||
.filter(|r| {
|
||||
if let Some(text) = &r.payload.text {
|
||||
keyword_filter.iter().any(|k| text.contains(k.as_str()))
|
||||
} else {
|
||||
false
|
||||
}
|
||||
})
|
||||
.take(limit)
|
||||
.collect();
|
||||
|
||||
Ok(filtered)
|
||||
}
|
||||
```
|
||||
|
||||
### 12.4 場景搜尋
|
||||
|
||||
#### 查詢類型 5: 找出特定場景
|
||||
|
||||
```sql
|
||||
-- PostgreSQL: 找出特定場景 ID 的 chunks
|
||||
SELECT * FROM chunks
|
||||
WHERE uuid = '1636719dc31f78ac'
|
||||
AND chunk_type = 'cut'
|
||||
AND (content->>'scene_id')::int = 5;
|
||||
|
||||
-- 找出包含轉場效果的 chunks
|
||||
SELECT * FROM chunks
|
||||
WHERE uuid = '1636719dc31f78ac'
|
||||
AND chunk_type = 'cut'
|
||||
AND content->>'transition_type' = 'dissolve';
|
||||
```
|
||||
|
||||
### 12.5 影片摘要
|
||||
|
||||
#### 查詢類型 6: 產生影片摘要
|
||||
|
||||
```sql
|
||||
-- 合併影片所有語句
|
||||
SELECT
|
||||
string_agg(content->>'text', ' ' ORDER BY start_time) as full_transcript
|
||||
FROM chunks
|
||||
WHERE uuid = '1636719dc31f78ac'
|
||||
AND chunk_type = 'sentence'
|
||||
AND content->>'text' IS NOT NULL;
|
||||
|
||||
-- 按場景聚合文字
|
||||
SELECT
|
||||
content->>'scene_id' as scene,
|
||||
string_agg(content->>'text', ' ' ORDER BY start_time) as scene_text
|
||||
FROM chunks
|
||||
WHERE uuid = '1636719dc31f78ac'
|
||||
AND chunk_type = 'cut'
|
||||
GROUP BY content->>'scene_id'
|
||||
ORDER BY MIN(start_time);
|
||||
```
|
||||
|
||||
### 12.6 常見查詢模式
|
||||
|
||||
| 查詢類型 | 描述 | 資料庫 | SQL/程式碼 |
|
||||
|----------|------|--------|-------------|
|
||||
| 語義搜尋 | 找相似內容 | Qdrant | `search(vector, limit)` |
|
||||
| 關鍵詞搜尋 | 精確文字匹配 | PostgreSQL | `ILIKE '%keyword%'` |
|
||||
| 時間範圍 | 特定時段 | Both | `start_time < end AND end_time > start` |
|
||||
| 場景搜尋 | 特定鏡頭 | PostgreSQL | `scene_id = N` |
|
||||
| 混合搜尋 | 向量+關鍵詞 | Both |結合以上兩種 |
|
||||
| 摘要產生 | 合併文字 | PostgreSQL | `string_agg()` |
|
||||
|
||||
---
|
||||
|
||||
## 13. 資料庫選擇建議
|
||||
|
||||
### 13.1 儲存策略
|
||||
|
||||
| 資料類型 | 主要儲存 | 備份/查詢 | 說明 |
|
||||
|----------|----------|-----------|------|
|
||||
| **Chunk 元數據** | PostgreSQL | MongoDB | 結構化查詢為主 |
|
||||
| **向量資料** | Qdrant | PostgreSQL | 向量搜尋為主 |
|
||||
| **全文檢索** | PostgreSQL | - | 關鍵詞搜尋 |
|
||||
| **日誌/歷史** | MongoDB | - | 靈活性為主 |
|
||||
|
||||
### 13.2 讀寫模式
|
||||
|
||||
| 場景 | 寫入 | 讀取 |
|
||||
|------|------|------|
|
||||
| **影片處理** | PostgreSQL + Qdrant | - |
|
||||
| **語義搜尋** | - | Qdrant |
|
||||
| **時間軸瀏覽** | - | PostgreSQL |
|
||||
| **系統分析** | MongoDB | MongoDB |
|
||||
|
||||
---
|
||||
|
||||
## 14. 相關文件
|
||||
## 10. 相關文件
|
||||
|
||||
- [JSON_OUTPUT_SPEC.md](./JSON_OUTPUT_SPEC.md) - JSON 輸出規範
|
||||
- [RUST_DEVELOPMENT.md](./RUST_DEVELOPMENT.md) - Rust 開發規範
|
||||
@@ -1,40 +1,5 @@
|
||||
---
|
||||
document_type: "reference_doc"
|
||||
service: "MOMENTRY_CORE"
|
||||
title: "Momentry Core 開發日誌"
|
||||
date: "2026-03-18"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "OpenCode"
|
||||
tags:
|
||||
- "開發日誌"
|
||||
- "momentry"
|
||||
- "core"
|
||||
ai_query_hints:
|
||||
- "查詢 Momentry Core 開發日誌 的內容"
|
||||
- "Momentry Core 開發日誌 的主要目的是什麼？"
|
||||
- "如何操作或實施 Momentry Core 開發日誌？"
|
||||
---
|
||||
|
||||
# Momentry Core 開發日誌
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-18 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
> **文檔維護開始**：2026-03-18
|
||||
> **⚠️ 補充說明**：事後補記（2026-03-18 以前），僅供參考。未來紀錄將即時記錄，參考價值較高。
|
||||
|
||||
@@ -185,7 +150,7 @@ TUI 顯示：
|
||||
- job:{uuid}:processor:{name}
|
||||
|
||||
### 備份系統整合
|
||||
參考 `docs_v1.0/IMPLEMENTATION/SERVICE_ADDITION_GUIDE.md` 設計規範，規劃 OutputDir 模組：
|
||||
參考 `docs/SERVICE_ADDITION_GUIDE.md` 設計規範，規劃 OutputDir 模組：
|
||||
|
||||
1. **環境變數**：
|
||||
- `MOMENTRY_OUTPUT_DIR` - JSON 輸出目錄
|
||||
@@ -238,8 +203,8 @@ TUI 顯示：
|
||||
|
||||
| 日期 | 檔案 | 說明 |
|
||||
|------|------|------|
|
||||
| 2026-03-18 | `docs_v1.0/REFERENCE/MOMENTRY_CORE_REDIS_KEYS.md` | Redis Key 設計規範 |
|
||||
| 2026-03-18 | `docs_v1.0/OPERATIONS/MOMENTRY_CORE_MONITORING.md` | 監控規範（暫定） |
|
||||
| 2026-03-18 | `docs/MOMENTRY_CORE_REDIS_KEYS.md` | Redis Key 設計規範 |
|
||||
| 2026-03-18 | `docs/MOMENTRY_CORE_MONITORING.md` | 監控規範（暫定） |
|
||||
| 2026-03-18 | `scripts/redis_publisher.py` | Redis 訊息發布模組 |
|
||||
|
||||
### 更新檔案
|
||||
@@ -248,7 +213,7 @@ TUI 顯示：
|
||||
|------|------|------|
|
||||
| 2026-03-17 | `Cargo.toml` | 新增 player feature |
|
||||
| 2026-03-17 | `src/lib.rs` | 新增 ui module exports |
|
||||
| 2026-03-18 | `docs_v1.0/REFERENCE/PENDING_ISSUES.md` | 新增問題 #2, #3 |
|
||||
| 2026-03-18 | `docs/PENDING_ISSUES.md` | 新增問題 #2, #3 |
|
||||
| 2026-03-18 | `src/core/storage/output_dir.rs` | 預設改為 `./output` |
|
||||
| 2026-03-18 | `scripts/yolo_processor.py` | 新增 --uuid 參數 + Redis |
|
||||
| 2026-03-18 | `scripts/cut_processor.py` | 新增 Redis |
|
||||
@@ -293,7 +258,7 @@ TUI 顯示：
|
||||
|
||||
### 問題 #3: Redis Message Bus 尚未實作
|
||||
- 狀態：已解決
|
||||
- 詳細設計：參考 `docs_v1.0/REFERENCE/MOMENTRY_CORE_REDIS_KEYS.md`
|
||||
- 詳細設計：參考 `docs/MOMENTRY_CORE_REDIS_KEYS.md`
|
||||
- 進度：Python 端 + Rust 端均已完成
|
||||
|
||||
---
|
||||
@@ -457,103 +422,3 @@ cargo run --bin momentry -- process <uuid>
|
||||
# 查詢進度
|
||||
curl http://127.0.0.1:3002/api/v1/progress/<uuid>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2026-03-18 (Dashboard)
|
||||
|
||||
### Web Dashboard 實作
|
||||
|
||||
**目標**：建立 Web 介面監控 momentry_core 處理進度
|
||||
|
||||
**技術選擇**：Static HTML + JavaScript (非 WASM)
|
||||
|
||||
**實作內容**：
|
||||
|
||||
| 元件 | 檔案 | 說明 |
|
||||
|------|------|------|
|
||||
| Dashboard | `momentry_dashboard/dist/index.html` | 靜態 HTML 頁面 |
|
||||
| API 代理 | Caddyfile port 3200 | 反向代理到 API server |
|
||||
|
||||
**功能**：
|
||||
- 影片列表顯示
|
||||
- 即時進度條 (每 5 秒自動刷新)
|
||||
- 搜尋功能
|
||||
- 處理器狀態 (ASR/CUT/YOLO/OCR/Face/Pose)
|
||||
|
||||
**訪問**：
|
||||
- Dashboard: http://localhost:3200
|
||||
- API: http://localhost:3200/api/v1/*
|
||||
|
||||
---
|
||||
|
||||
## 發生問題記錄
|
||||
|
||||
### HTTP API 問題
|
||||
|
||||
1. **語法錯誤** (main.rs)
|
||||
- 位置：lines 297-322
|
||||
- 原因：重複的程式碼區塊
|
||||
- 解決：移除重複區塊
|
||||
|
||||
2. **DB 連線池耗盡**
|
||||
- 原因：預設 5 個連線不足
|
||||
- 解決：增加到 10 個連線
|
||||
|
||||
3. **PostgreSQL shutdown 狀態**
|
||||
- 原因：共享記憶體未釋放
|
||||
- 解決：殺掉 stale 連線
|
||||
|
||||
### WASM Dashboard 問題
|
||||
|
||||
1. **Yew 版本問題**
|
||||
- 嘗試：yew 0.21 → 0.23
|
||||
- 問題：feature 名稱變更 (`web-sys` → `web_sys` → `csr`)
|
||||
- 解決：放棄 WASM，改用靜態 HTML
|
||||
|
||||
2. **編譯錯誤**
|
||||
- `wasm32-unknown-unknown` target 未安裝
|
||||
- 解決：`rustup target add wasm32-unknown-unknown`
|
||||
|
||||
3. **Yew 0.23 API 變更**
|
||||
- Properties 需要 PartialEq derive
|
||||
- 多處 API 語法變更
|
||||
- 放棄 WASM 方案
|
||||
|
||||
### Gitea Push 問題
|
||||
|
||||
1. **Remote URL 錯誤**
|
||||
- 原因：使用 localhost:3000 而非 gitea.momentry.ddns.net
|
||||
- 解決：建立新 repo `momentry_core_0_1`
|
||||
|
||||
2. **認證問題**
|
||||
- SSH key 未授權
|
||||
- 密碼認證成功推送
|
||||
|
||||
### Caddy 設定問題
|
||||
|
||||
1. **API 代理順序**
|
||||
- 問題：try_files 在 reverse_proxy 之前導致 API 回傳 HTML
|
||||
- 解決：使用 `handle` 區塊明確定義順序
|
||||
|
||||
```caddyfile
|
||||
:3200 {
|
||||
handle /api/* {
|
||||
reverse_proxy localhost:3002
|
||||
}
|
||||
handle {
|
||||
root * /Users/accusys/momentry_dashboard/dist
|
||||
try_files {path} /index.html
|
||||
file_server
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 未來工作
|
||||
|
||||
- [ ] 修復 WASM Dashboard (Yew 0.23 相容性)
|
||||
- [ ] 新增影片播放器整合
|
||||
- [ ] WebSocket 實時推送
|
||||
- [ ] 移動端響應式設計
|
||||
@@ -1,45 +0,0 @@
|
||||
# 槍枝檢測模型 Charade 評估報告
|
||||
|
||||
**Date:** 2026-05-10
|
||||
**模型:** YOLOv8n fine-tuned on Roboflow gun dataset (905 images)
|
||||
**Classes:** grenade (0), knife (1), pistol (2), rifle (3)
|
||||
**Weights:** `models/gun/gun_detector/weights/best.pt` (6MB)
|
||||
|
||||
## 訓練
|
||||
|
||||
- **Dataset**: 905 images, Roboflow CC BY 4.0
|
||||
- **Validation mAP50**: 0.813
|
||||
- **問題**: 訓練資料全為近距離槍枝特寫，與 Charade 電影中的中遠景畫面分布完全不同
|
||||
|
||||
## Charade 測試結果
|
||||
|
||||
### 系統掃描（24 取樣點 @ 每 300s）
|
||||
|
||||
| 時間 | 類別 | 信心 | 判定 |
|
||||
|------|------|------|------|
|
||||
| t=600s | pistol×2, rifle | 0.16–0.30 | ❌ FP |
|
||||
| t=1200s | knife | 0.37 | ❌ FP |
|
||||
| t=1800s | pistol | 0.19 | ❌ FP |
|
||||
| t=2400s | knife | 0.18 | ❌ FP |
|
||||
| t=3000s | pistol | 0.16 | ❌ FP |
|
||||
| t=5400s | pistol×2 | 0.45, 0.17 | ❌ FP（郵票被誤判為槍） |
|
||||
| t=6600s | grenade | 0.22 | ❌ FP |
|
||||
|
||||
### 密集掃描（ASR trigger）
|
||||
|
||||
在 ASR dialogue 提到 "gun" 的時間點附近跑 gun detector，找到 5 個 pistol/gun 觸發（3188s / 5461s / 6309s / 6377s / 6479s），confidence 0.300-0.387。
|
||||
|
||||
**結果：全部為 false positive。** 訓練效果非常不好 — 模型在電影中遠景畫面完全失效。
|
||||
|
||||
## 結論
|
||||
|
||||
1. 訓練資料與推論場景 distribution mismatch 嚴重
|
||||
2. 905 張 Roboflow 近距離特寫 → Charade 的中遠景手持/部分遮蔽槍枝 → 模型無法泛化
|
||||
3. 建議：收集電影真實槍枝畫面（200-500 張動作片片段）重新訓練
|
||||
4. 在此之前，槍枝搜尋只能靠 ASR dialogue keyword matching + 人工確認
|
||||
|
||||
## 相關檔案
|
||||
|
||||
- `models/gun/gun_detector/weights/best.pt` — 模型權重（效果不佳）
|
||||
- `output_dev/gun_detections/` — 偵測截圖（全部 FP）
|
||||
- `scripts/object_search_agent.py` — 整合搜尋 agent（gun detector 偵測結果僅供參考）
|
||||
@@ -1,73 +0,0 @@
|
||||
# Gun Detector Scan Report — YOLOv8n on Charade (1963)
|
||||
|
||||
**Date:** 2026-05-10
|
||||
**Model:** `models/gun/gun_detector/weights/best.pt`
|
||||
**Base:** YOLOv8n fine-tuned on Roboflow gun dataset (905 images)
|
||||
**Classes:** grenade, knife, pistol, rifle
|
||||
**Scan script:** `scripts/gun_detector_scan.py`
|
||||
|
||||
## Scan Method
|
||||
|
||||
- **121 scan points**: 2 ASR "gun" mentions + 114 fixed intervals (60s) + 5 original hit timestamps
|
||||
- **Per point**: scan ±30 frames at every 3rd frame = ~20 frames per point
|
||||
- **Total frames processed**: ~2,420
|
||||
- **Runtime**: ~2 min
|
||||
|
||||
## Results
|
||||
|
||||
| Class | Detections | Top Confidence |
|
||||
|-------|-----------|---------------|
|
||||
| pistol | **82** | 0.887 |
|
||||
| rifle | 55 | 0.822 |
|
||||
| grenade | 35 | 0.797 |
|
||||
| knife | 38 | 0.810 |
|
||||
| **Total** | **210** (after dedup) | — |
|
||||
|
||||
## Original 5 Pistol Timestamps
|
||||
|
||||
| Timestamp | Original | This Scan | Delta |
|
||||
|-----------|----------|-----------|-------|
|
||||
| 3188s (53:08) | pistol 0.387 | ✅ **0.474** | +22% |
|
||||
| 5461s (91:01) | pistol 0.355 | ✅ **0.346** | −3% |
|
||||
| 6309s (1:45:09) | pistol 0.374 | ❌ Not found | — |
|
||||
| 6377s (1:46:17) | gun 0.316 | ✅ **0.757** | +140% |
|
||||
| 6479s (1:47:59) | pistol 0.300 | ✅ **0.815** | +172% |
|
||||
|
||||
## Top Pistol Detections
|
||||
|
||||
| Time | Confidence | Image |
|
||||
|------|-----------|-------|
|
||||
| 84:00 (5040s) | **0.887** | `5040s_pistol_0.887.jpg` |
|
||||
| 90:00 (5400s) | **0.816** | `5400s_pistol_0.816.jpg` |
|
||||
| 108:00 (6480s) | **0.815** | `6480s_pistol_0.815.jpg` |
|
||||
| 48:59 (2939s) | **0.805** | `2939s_pistol_0.805.jpg` |
|
||||
| 53:07 (3187s) | **0.474** | `3187s_pistol_0.474.jpg` |
|
||||
| 91:00 (5459s) | **0.346** | `5459s_pistol_0.346.jpg` |
|
||||
|
||||
## Analysis
|
||||
|
||||
### Model Performance
|
||||
|
||||
Compared to the original evaluation (May 7, 24 sample points, all FP):
|
||||
|
||||
- This scan found **significantly more detections** (210 vs 7)
|
||||
- Confidence values are **much higher** (0.887 vs 0.45 max)
|
||||
- 4/5 original pistol timestamps recovered
|
||||
|
||||
### Cautions
|
||||
|
||||
1. **Training data mismatch**: Model was trained on 905 close-up gun photos, NOT movie frames. High confidence ≠ real gun.
|
||||
2. **Stamp false positive confirmed**: t=5400s (identified in original eval as stamp → pistol) continues to fire at 0.816
|
||||
3. **Pattern suggests overconfidence**: Many detections at regular intervals (every 60s, same objects) suggest the model is detecting non-gun objects with high confidence
|
||||
|
||||
### Verified Findings
|
||||
|
||||
The original 5 pistol images from the gun_detections/ directory (3188s, 5461s, 6309s, 6377s, 6479s) were all produced by the same YOLOv8n model. The user previously stated that none of these have been confirmed as real guns.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `output_dev/gun_detections/gun_detections.json` | All 210 deduped detections |
|
||||
| `output_dev/gun_detections/*.jpg` | Annotated screenshots (one per detection) |
|
||||
| `scripts/gun_detector_scan.py` | Scan script (reproducible) |
|
||||
@@ -1,41 +1,5 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "CADDY"
|
||||
title: "Caddy 安裝指南 (本地部署)"
|
||||
date: "2026-03-16"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "caddy"
|
||||
- "reverse-proxy"
|
||||
- "web-server"
|
||||
- "macos"
|
||||
ai_query_hints:
|
||||
- "如何安裝 Caddy 反向代理？"
|
||||
- "Caddy 配置檔案路徑在哪裡？"
|
||||
- "如何配置 Caddy 開機自動啟動？"
|
||||
---
|
||||
|
||||
# Caddy 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-16 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 Caddy Web Server，配置為本地部署，作為反向代理伺服器。
|
||||
@@ -1,41 +1,5 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "GITEA"
|
||||
title: "Gitea 安裝指南 (本地部署)"
|
||||
date: "2026-03-15"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "gitea"
|
||||
- "git-server"
|
||||
- "version-control"
|
||||
- "macos"
|
||||
ai_query_hints:
|
||||
- "如何安裝 Gitea 本地 Git 伺服器？"
|
||||
- "Gitea 數據目錄路徑在哪裡？"
|
||||
- "如何配置 Gitea 開機自動啟動？"
|
||||
---
|
||||
|
||||
# Gitea 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-15 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-15 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 Gitea Git 服務，配置為本地部署。
|
||||
-36
@@ -1,41 +1,5 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "MARIADB"
|
||||
title: "MariaDB 安裝指南 (本地部署)"
|
||||
date: "2026-03-16"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "mariadb"
|
||||
- "database"
|
||||
- "macos"
|
||||
- "sql"
|
||||
ai_query_hints:
|
||||
- "如何安裝 MariaDB 資料庫？"
|
||||
- "MariaDB 連線資訊為何？"
|
||||
- "如何備份與恢復 MariaDB 數據？"
|
||||
---
|
||||
|
||||
# MariaDB 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-16 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 MariaDB，配置為本地部署，支援遠端訪問。
|
||||
+24
-69
@@ -1,41 +1,5 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "MONGODB"
|
||||
title: "MongoDB 安裝指南 (本地部署)"
|
||||
date: "2026-03-15"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "mongodb"
|
||||
- "nosql"
|
||||
- "database"
|
||||
- "macos"
|
||||
ai_query_hints:
|
||||
- "如何安裝 MongoDB 資料庫？"
|
||||
- "MongoDB 連線資訊為何？"
|
||||
- "如何配置 MongoDB 開機自動啟動？"
|
||||
---
|
||||
|
||||
# MongoDB 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-15 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-15 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 MongoDB Community Edition，配置為本地部署，支援遠端訪問。
|
||||
@@ -47,8 +11,8 @@ ai_query_hints:
|
||||
| 項目 | 狀態 |
|
||||
|------|------|
|
||||
| MongoDB (mongodb-community) | ✅ 已安裝 v8.2.6 |
|
||||
| 數據目錄 | /opt/homebrew/var/mongodb |
|
||||
| 日誌目錄 | /Users/accusys/momentry/log |
|
||||
| 數據目錄 | 保留 (/Users/accusys/momentry/var) - 共用 |
|
||||
| 日誌目錄 | 保留 (/Users/accusys/momentry/log) - 共用 |
|
||||
|
||||
---
|
||||
|
||||
@@ -76,9 +40,9 @@ sudo launchctl list | grep mongo
|
||||
|
||||
### Step 2: 數據目錄 (已存在 - 共用)
|
||||
|
||||
數據目錄使用 homebrew 預設位置:
|
||||
- 數據目錄: `/opt/homebrew/var/mongodb`
|
||||
- 配置目錄: `/opt/homebrew/etc/mongod.conf`
|
||||
數據目錄已存在，無需建立:
|
||||
- 數據目錄: `/Users/accusys/momentry/var`
|
||||
- 配置目錄: `/Users/accusys/momentry/etc/mongodb`
|
||||
- 日誌目錄: `/Users/accusys/momentry/log`
|
||||
|
||||
**建立配置目錄和日誌文件**:
|
||||
@@ -97,19 +61,15 @@ chown -R accusys:staff /Users/accusys/momentry
|
||||
|
||||
---
|
||||
|
||||
### Step 3: 使用 LaunchAgent 啟動 (開機自動)
|
||||
### Step 3: 啟動 MongoDB (後台執行)
|
||||
|
||||
```bash
|
||||
# 複製 plist 到 LaunchDaemons 目錄 (開機自動需要 root 權限)
|
||||
sudo cp /Users/accusys/momentry_core_0.1/momentry_runtime/plist/com.momentry.mongodb.plist \
|
||||
/Library/LaunchDaemons/
|
||||
|
||||
# 載入並啟動
|
||||
sudo launchctl load /Library/LaunchDaemons/com.momentry.mongodb.plist
|
||||
|
||||
# 驗證
|
||||
launchctl list | grep mongodb
|
||||
pgrep -a mongod
|
||||
nohup /opt/homebrew/bin/mongod \
|
||||
--dbpath /Users/accusys/momentry/var \
|
||||
--logpath /Users/accusys/momentry/log/mongodb.log \
|
||||
--port 27017 \
|
||||
--bind_ip 0.0.0.0 \
|
||||
> /Users/accusys/momentry/log/mongodb.log 2>&1 &
|
||||
```
|
||||
|
||||
---
|
||||
@@ -130,20 +90,14 @@ db.createUser({
|
||||
|
||||
---
|
||||
|
||||
### Step 4: 驗證安裝
|
||||
### Step 5: 使用 plist 開機自動啟動
|
||||
|
||||
```bash
|
||||
# 檢查進程
|
||||
pgrep -a mongod
|
||||
# 複製 plist 到 LaunchDaemons 目錄
|
||||
sudo cp /Users/accusys/momentry_core_0.1/momentry_runtime/plist/com.momentry.mongodb.plist /Library/LaunchDaemons/
|
||||
|
||||
# 檢查端口
|
||||
lsof -i :27017
|
||||
|
||||
# 測試連線
|
||||
mongosh --eval "db.adminCommand('ping')"
|
||||
|
||||
# 檢查 LaunchAgent
|
||||
launchctl list | grep mongodb
|
||||
# 載入並啟動
|
||||
sudo launchctl load /Library/LaunchDaemons/com.momentry.mongodb.plist
|
||||
```
|
||||
|
||||
---
|
||||
@@ -311,11 +265,12 @@ tail -20 /Users/accusys/momentry/log/mongodb.error.log
|
||||
### 啟動/停止
|
||||
|
||||
```bash
|
||||
# 使用 LaunchAgent (開機自動 - LaunchDaemons 目錄)
|
||||
sudo launchctl load /Library/LaunchDaemons/com.momentry.mongodb.plist # 啟動
|
||||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.mongodb.plist # 停止
|
||||
# 停止
|
||||
pkill mongod
|
||||
# 或
|
||||
kill <PID>
|
||||
|
||||
# 手動啟動 (僅除錯用)
|
||||
# 啟動 (後台)
|
||||
nohup /opt/homebrew/bin/mongod \
|
||||
--dbpath /Users/accusys/momentry/var \
|
||||
--logpath /Users/accusys/momentry/log/mongodb.log \
|
||||
@@ -323,8 +278,8 @@ nohup /opt/homebrew/bin/mongod \
|
||||
--bind_ip 0.0.0.0 \
|
||||
> /Users/accusys/momentry/log/mongodb.log 2>&1 &
|
||||
|
||||
# 強制停止
|
||||
pkill mongod
|
||||
# 使用 plist (開機自動啟動)
|
||||
sudo launchctl load /Library/LaunchDaemons/com.momentry.mongodb.plist
|
||||
```
|
||||
|
||||
---
|
||||
@@ -1,41 +1,5 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "N8N"
|
||||
title: "n8n 安裝指南 (本地部署)"
|
||||
date: "2026-03-16"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "n8n"
|
||||
- "workflow"
|
||||
- "automation"
|
||||
- "macos"
|
||||
ai_query_hints:
|
||||
- "如何安裝 n8n 自動化平台？"
|
||||
- "n8n Webhook 配置方式為何？"
|
||||
- "如何匯出匯入 n8n Workflow？"
|
||||
---
|
||||
|
||||
# n8n 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-16 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 n8n 工作流自動化平台，配置為本地部署，使用 Queue 模式。
|
||||
@@ -46,22 +10,13 @@ ai_query_hints:
|
||||
|
||||
| 項目 | 狀態 |
|
||||
|------|------|
|
||||
| n8n | ✅ 已安裝 v2.12.3 |
|
||||
| n8n | ✅ 已安裝 v2.3.5 |
|
||||
| 數據目錄 | /Users/accusys/momentry/var/n8n/ |
|
||||
| 日誌目錄 | /Users/accusys/momentry/log/ |
|
||||
| Main Plist | /Library/LaunchDaemons/com.momentry.n8n.main.plist |
|
||||
| Worker Plist | /Library/LaunchDaemons/com.momentry.n8n.worker.plist |
|
||||
| 數據庫 | PostgreSQL (n8n) |
|
||||
| 隊列 | Redis |
|
||||
| Launchd 狀態 | ✅ Main + Worker 已註冊 |
|
||||
| RunAtLoad | ✅ 已設定 |
|
||||
| KeepAlive | ✅ 已設定 |
|
||||
|
||||
### 重要更新 (2026-03-24)
|
||||
|
||||
1. **n8n Main + Worker**: 兩個服務都使用自定義 plist
|
||||
2. **Runner 禁用**: 為避免端口衝突，Main 服務設定 `N8N_RUNNERS_ENABLED=false`
|
||||
3. **Worker 端口**: Worker 使用 5681, 5682, 5690, 5691 端口
|
||||
|
||||
---
|
||||
|
||||
@@ -77,7 +32,7 @@ brew install n8n
|
||||
**驗證**:
|
||||
```bash
|
||||
n8n --version
|
||||
# 2.12.3
|
||||
# 2.3.5
|
||||
```
|
||||
|
||||
---
|
||||
@@ -262,9 +217,9 @@ ps aux | grep "n8n.*worker" | grep -v grep && echo " ✗ 仍在運行" || echo
|
||||
echo "3. Port 8085:"
|
||||
lsof -i :8085 > /dev/null 2>&1 && echo " ✗ 仍被佔用" || echo " ✓ 已釋放"
|
||||
|
||||
# 3. Port 5679 (Worker)
|
||||
echo "4. Port 5679 (Worker):"
|
||||
lsof -i :5679 > /dev/null 2>&1 && echo " ✗ 仍被佔用" || echo " ✓ 已釋放"
|
||||
# 3. Port 5690-5691
|
||||
echo "4. Port 5690-5691:"
|
||||
lsof -i :5690 > /dev/null 2>&1 && echo " ✗ 仍被佔用" || echo " ✓ 已釋放"
|
||||
|
||||
# 4. n8n 命令
|
||||
echo "5. n8n 命令:"
|
||||
@@ -332,7 +287,8 @@ ps aux | grep n8n | grep -v grep
|
||||
|
||||
# 2. 檢查 Port
|
||||
lsof -i :5678
|
||||
lsof -i :5679
|
||||
lsof -i :5690
|
||||
lsof -i :5691
|
||||
|
||||
# 3. 測試連線
|
||||
curl http://localhost:5678/
|
||||
@@ -369,7 +325,8 @@ sudo launchctl list | grep n8n
|
||||
| 服務 | Port |
|
||||
|------|------|
|
||||
| Main | 5678 |
|
||||
| Task Broker (Worker 連接) | 5679 |
|
||||
| Worker Broker | 5690 |
|
||||
| Worker Health Check | 5691 |
|
||||
|
||||
---
|
||||
|
||||
@@ -502,7 +459,7 @@ sudo launchctl load /Library/LaunchDaemons/com.momentry.n8n.main.plist
|
||||
|
||||
- 版本: 2.3.5
|
||||
- Main Port: 5678
|
||||
- Task Broker (Worker): 5679
|
||||
- Worker Ports: 5690-5691
|
||||
- 數據目錄: /Users/accusys/momentry/var/n8n/
|
||||
- 日誌目錄: /Users/accusys/momentry/log/
|
||||
- 數據庫: PostgreSQL n8n
|
||||
+1
-37
@@ -1,41 +1,5 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "OLLAMA"
|
||||
title: "Ollama 安裝指南 (本地部署)"
|
||||
date: "2026-03-15"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "ollama"
|
||||
- "llm"
|
||||
- "ai-inference"
|
||||
- "macos"
|
||||
ai_query_hints:
|
||||
- "如何安裝 Ollama 本地 LLM 推理引擎？"
|
||||
- "如何下載 Ollama 模型？"
|
||||
- "Ollama API 端點為何？"
|
||||
---
|
||||
|
||||
# Ollama 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-15 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-15 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 Ollama，配置為本地部署，用於運行大型語言模型 (LLM)。
|
||||
@@ -48,7 +12,7 @@ ai_query_hints:
|
||||
|------|------|
|
||||
| Ollama | ✅ 已安裝 v0.13.5 |
|
||||
| Port | 11434 |
|
||||
| Models 目錄 | /Users/accusys/momentry/var/ollama/models |
|
||||
| Models 目錄 | /Users/accusys/.ollama/models/ |
|
||||
| 日誌目錄 | /Users/accusys/momentry/log/ |
|
||||
| Plist | /Library/LaunchDaemons/com.momentry.ollama.plist |
|
||||
|
||||
@@ -1,41 +1,5 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "PHP"
|
||||
title: "PHP 安裝指南 (本地部署)"
|
||||
date: "2026-03-16"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "php"
|
||||
- "web-server"
|
||||
- "wordpress"
|
||||
- "macos"
|
||||
ai_query_hints:
|
||||
- "如何安裝 PHP 環境？"
|
||||
- "PHP 配置優化建議為何？"
|
||||
- "如何配置 PHP-FPM 與 Nginx/Caddy？"
|
||||
---
|
||||
|
||||
# PHP 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-16 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 PHP 及 PHP-FPM，配置為本地部署。
|
||||
+1
-46
@@ -1,41 +1,5 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "POSTGRESQL"
|
||||
title: "PostgreSQL 安裝指南 (本地部署)"
|
||||
date: "2026-03-15"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "postgresql"
|
||||
- "database"
|
||||
- "macos"
|
||||
- "sql"
|
||||
ai_query_hints:
|
||||
- "如何安裝 PostgreSQL 資料庫？"
|
||||
- "PostgreSQL 數據目錄路徑在哪裡？"
|
||||
- "如何卸載 PostgreSQL 並保留數據？"
|
||||
---
|
||||
|
||||
# PostgreSQL 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-15 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-15 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 PostgreSQL，配置為本地部署，支援遠端訪問。
|
||||
@@ -47,18 +11,9 @@ ai_query_hints:
|
||||
| 項目 | 狀態 |
|
||||
|------|------|
|
||||
| PostgreSQL | ✅ 已安裝 v18.1 |
|
||||
| 數據目錄 | /Users/accusys/momentry/var/postgresql |
|
||||
| 數據目錄 | /Users/accusys/momentry/var/postgresql/ |
|
||||
| 日誌目錄 | /Users/accusys/momentry/log/ |
|
||||
| Plist | /Library/LaunchDaemons/com.momentry.postgresql.plist |
|
||||
| Launchd 狀態 | ✅ 已註冊 |
|
||||
| RunAtLoad | ✅ 已設定 |
|
||||
| KeepAlive | ✅ 已設定 |
|
||||
|
||||
### 重要更新 (2026-03-24)
|
||||
|
||||
1. **資料目錄已變更**: 從 `/opt/homebrew/var/postgresql@18` 遷移到 `/Users/accusys/momentry/var/postgresql`
|
||||
2. **統一管理**: 所有 Momentry 服務現在都使用 `/Library/LaunchDaemons/` 下的自定義 plist
|
||||
3. **避免衝突**: 刪除了 homebrew plist，避免 reboot 後使用舊資料目錄
|
||||
|
||||
---
|
||||
|
||||
@@ -1,41 +1,5 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "QDRANT"
|
||||
title: "Qdrant 安裝指南 (本地部署)"
|
||||
date: "2026-03-16"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "qdrant"
|
||||
- "vector-database"
|
||||
- "ai-search"
|
||||
- "macos"
|
||||
ai_query_hints:
|
||||
- "如何安裝 Qdrant 向量資料庫？"
|
||||
- "Qdrant 連線資訊為何？"
|
||||
- "如何配置 Qdrant Collection？"
|
||||
---
|
||||
|
||||
# Qdrant 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-16 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 Qdrant Vector Database，配置為本地部署，支援遠端訪問。
|
||||
+6
-140
@@ -1,43 +1,5 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "REDIS"
|
||||
title: "Redis 安裝指南 (本地部署)"
|
||||
date: "2026-03-15"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "redis"
|
||||
- "cache"
|
||||
- "key-value"
|
||||
- "macos"
|
||||
ai_query_hints:
|
||||
- "如何安裝 Redis 快取伺服器？"
|
||||
- "Redis 連線資訊為何？"
|
||||
- "如何配置 Redis 持久化？"
|
||||
---
|
||||
|
||||
# Redis 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-15 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-15 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
| V1.1 | 2026-03-21 | 更新 rust redis crate 版本至 0.32.7 | OpenCode | - |
|
||||
| V1.2 | 2026-03-21 | 添加 Redis 用戶配置說明 | OpenCode | - |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 Redis，配置為本地部署，支援遠端訪問。
|
||||
@@ -49,7 +11,7 @@ ai_query_hints:
|
||||
| 項目 | 狀態 |
|
||||
|------|------|
|
||||
| Redis | ✅ 已安裝 v8.4.0 |
|
||||
| 數據目錄 | /opt/homebrew/var/db/redis/ |
|
||||
| 數據目錄 | /Users/accusys/momentry/var/redis/ |
|
||||
| 日誌目錄 | /Users/accusys/momentry/log/ |
|
||||
| Plist | /Library/LaunchDaemons/com.momentry.redis.plist |
|
||||
|
||||
@@ -398,104 +360,8 @@ sudo launchctl load /Library/LaunchDaemons/com.momentry.redis.plist
|
||||
|
||||
## 版本資訊
|
||||
|
||||
| 項目 | 值 |
|
||||
|------|-----|
|
||||
| Redis Server | 8.4.0 |
|
||||
| Rust redis crate | 0.32.7 |
|
||||
| Port | 6379 |
|
||||
| Password | accusys |
|
||||
| 數據目錄 | /Users/accusys/momentry/var/redis/ |
|
||||
| 日誌目錄 | /Users/accusys/momentry/log/ |
|
||||
|
||||
---
|
||||
|
||||
## Rust redis crate 版本
|
||||
|
||||
Cargo.toml 中的 redis 依賴：
|
||||
|
||||
```toml
|
||||
redis = { version = "0.32", features = ["tokio-comp"] }
|
||||
```
|
||||
|
||||
### 版本歷史
|
||||
|
||||
| 版本 | 日期 | 變更 |
|
||||
|------|------|-------|
|
||||
| 0.25.4 | - | 原始版本（有未來相容性警告） |
|
||||
| 0.32.7 | 2026-03-21 | **升級** - 修復 Rust 2024 never type 回退問題 |
|
||||
|
||||
### 升級說明
|
||||
|
||||
升級到 0.32.x 的優點：
|
||||
- 修復 Rust 2024 edition 未來相容性問題
|
||||
- API 完全向後相容
|
||||
- 無需修改現有程式碼
|
||||
|
||||
---
|
||||
|
||||
## Redis 用戶配置說明
|
||||
|
||||
### 當前狀態
|
||||
|
||||
| 項目 | 狀態 |
|
||||
|------|------|
|
||||
| 用戶類型 | 僅有 `default` 用戶 |
|
||||
| 自訂用戶 | ❌ 未配置 |
|
||||
| ACL 持久化 | ❌ 未配置 |
|
||||
|
||||
### Redis ACL 狀態
|
||||
|
||||
```bash
|
||||
# 查看 ACL
|
||||
redis-cli -a accusys ACL LIST
|
||||
|
||||
# 輸出:
|
||||
# user default on sanitize-payload #hash ~* &* +@all
|
||||
```
|
||||
|
||||
### 連線格式說明
|
||||
|
||||
| 格式 | 狀態 | 說明 |
|
||||
|------|------|------|
|
||||
| `redis://:accusys@localhost:6379` | ✅ 正確 | 使用默認用戶 + 密碼 |
|
||||
| `redis://accusys:accusys@localhost:6379` | ❌ 失敗 | 用戶 `accusys` 不存在 |
|
||||
|
||||
### 為何用戶名不可用
|
||||
|
||||
1. **Redis 啟動方式**：使用 `--requirepass` 參數，僅設定默認用戶密碼
|
||||
2. **無 ACL 配置文件**：未指定 `--aclfile` 參數
|
||||
3. **動態建立用戶**：手動建立的用戶不會持久化（重啟後消失）
|
||||
|
||||
### 解決方案
|
||||
|
||||
#### 方案 A：使用默認用戶（現行）
|
||||
|
||||
```env
|
||||
REDIS_URL=redis://:accusys@localhost:6379
|
||||
```
|
||||
|
||||
**適用於**：單一應用、簡單部署
|
||||
|
||||
#### 方案 B：建立 ACL 配置文件
|
||||
|
||||
```bash
|
||||
# 1. 建立 ACL 文件
|
||||
cat > /Users/accusys/momentry/etc/redis/users.acl << 'EOF'
|
||||
user default on sanitize-payload ~* &* +@all >accusys
|
||||
user accusys on sanitize-payload ~* &* +@all >accusys
|
||||
EOF
|
||||
|
||||
# 2. 修改 plist (添加 --aclfile 參數)
|
||||
# --aclfile /Users/accusys/momentry/etc/redis/users.acl
|
||||
|
||||
# 3. 重啟 Redis
|
||||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.redis.plist
|
||||
sudo launchctl load /Library/LaunchDaemons/com.momentry.redis.plist
|
||||
```
|
||||
|
||||
**適用於**：多應用、需要用戶隔離
|
||||
|
||||
### 參考
|
||||
|
||||
- 問題追蹤：`docs_v1.0/REFERENCE/PENDING_ISSUES.md` 問題 #5
|
||||
- 測試結果：2026-03-21 Redis 認證測試
|
||||
- 版本: 8.4.0
|
||||
- Port: 6379
|
||||
- Password: accusys
|
||||
- 數據目錄: /Users/accusys/momentry/var/redis/
|
||||
- 日誌目錄: /Users/accusys/momentry/log/
|
||||
-36
@@ -1,41 +1,5 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "RUSTDESK"
|
||||
title: "RustDesk 安裝指南 (本地部署)"
|
||||
date: "2026-03-15"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "rustdesk"
|
||||
- "remote-desktop"
|
||||
- "screen-sharing"
|
||||
- "macos"
|
||||
ai_query_hints:
|
||||
- "如何安裝 RustDesk 遠端桌面？"
|
||||
- "RustDesk 伺服器配置方式為何？"
|
||||
- "如何配置 RustDesk 中繼伺服器？"
|
||||
---
|
||||
|
||||
# RustDesk 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-15 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-15 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 RustDesk 遠端桌面服務，配置為本地部署。
|
||||
@@ -0,0 +1,360 @@
|
||||
# SFTPGo 安裝指南 (本地部署)
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 SFTPGo，配置為本地部署，用於 SFTP/FTP/WebDAV 檔案傳輸服務。
|
||||
|
||||
---
|
||||
|
||||
## 當前狀態
|
||||
|
||||
| 項目 | 狀態 |
|
||||
|------|------|
|
||||
| SFTPGo | ✅ 已安裝 v2.7.0 |
|
||||
| Port | 8080 (HTTP), 2022 (SFTP) |
|
||||
| 配置目錄 | /Users/accusys/momentry/etc/sftpgo/ |
|
||||
| 日誌目錄 | /Users/accusys/momentry/log/ |
|
||||
| Plist | /Library/LaunchDaemons/com.momentry.sftpgo.plist |
|
||||
|
||||
---
|
||||
|
||||
## 安裝步驟
|
||||
|
||||
### Step 1: 安裝 SFTPGo (使用 brew)
|
||||
|
||||
```bash
|
||||
# 安裝 SFTPGo
|
||||
brew install sftpgo
|
||||
```
|
||||
|
||||
**驗證**:
|
||||
```bash
|
||||
sftpgo --version
|
||||
# SFTPGo 2.7.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: 建立目錄
|
||||
|
||||
```bash
|
||||
# 建立配置目錄
|
||||
mkdir -p /Users/accusys/momentry/etc/sftpgo
|
||||
|
||||
# 建立日誌目錄
|
||||
mkdir -p /Users/accusys/momentry/log
|
||||
|
||||
# 建立工作目錄
|
||||
mkdir -p /Users/accusys/workspace/sftpgo
|
||||
|
||||
# 建立日誌文件
|
||||
touch /Users/accusys/momentry/log/sftpgo.log
|
||||
touch /Users/accusys/momentry/log/sftpgo.error.log
|
||||
|
||||
# 設定權限
|
||||
chown -R accusys:staff /Users/accusys/momentry/etc/sftpgo
|
||||
chown -R accusys:staff /Users/accusys/momentry/log
|
||||
chown -R accusys:staff /Users/accusys/workspace/sftpgo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3: 建立設定檔
|
||||
|
||||
建立 `/Users/accusys/momentry/etc/sftpgo/sftpgo.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"common": {
|
||||
"idle_timeout": 15,
|
||||
"upload_mode": 0,
|
||||
"max_per_host_connections": 20
|
||||
},
|
||||
"users": [
|
||||
{
|
||||
"username": "accusys",
|
||||
"password": "",
|
||||
"public_keys": [],
|
||||
"home_dir": "/Users/accusys/workspace/sftpgo",
|
||||
"uid": 501,
|
||||
"gid": 20,
|
||||
"permissions": {
|
||||
"/": ["*"]
|
||||
}
|
||||
}
|
||||
],
|
||||
"httpd": {
|
||||
"bind_port": 8080,
|
||||
"bind_address": "0.0.0.0"
|
||||
},
|
||||
"ftpd": {
|
||||
"bind_port": 21,
|
||||
"bind_address": "0.0.0.0"
|
||||
},
|
||||
"sftpd": {
|
||||
"bind_port": 2022,
|
||||
"bind_address": "0.0.0.0"
|
||||
},
|
||||
"webdavd": {
|
||||
"bind_port": 0,
|
||||
"bind_address": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4: 使用 plist 開機自動啟動
|
||||
|
||||
```bash
|
||||
# 複製 plist 到 LaunchDaemons 目錄
|
||||
sudo cp /Users/accusys/momentry_core_0.1/momentry_runtime/plist/com.momentry.sftpgo.plist /Library/LaunchDaemons/
|
||||
|
||||
# 載入並啟動
|
||||
sudo launchctl load /Library/LaunchDaemons/com.momentry.sftpgo.plist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 監控配置
|
||||
|
||||
### 添加到監控配置
|
||||
|
||||
在 `monitor/config/monitor_config.yaml` 中添加：
|
||||
|
||||
```yaml
|
||||
service:
|
||||
services:
|
||||
- name: "sftpgo"
|
||||
type: "http"
|
||||
port: 8080
|
||||
host: "localhost"
|
||||
check_url: "http://localhost:8080/api/v2/info"
|
||||
timeout: 5
|
||||
enabled: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 卸載步驟
|
||||
|
||||
### 重要: 路徑說明
|
||||
|
||||
| 路徑 | 類型 | 說明 |
|
||||
|------|------|------|
|
||||
| `/Users/accusys/momentry/etc/sftpgo/` | 配置 | **不要刪除** - SFTPGo 配置 |
|
||||
| `/Users/accusys/momentry/log/` | 日誌 | **不要刪除** - 日誌目錄 |
|
||||
| `/Users/accusys/workspace/sftpgo/` | 數據 | **不要刪除** - 上傳檔案目錄 |
|
||||
| `/opt/homebrew/opt/sftpgo/` | 安裝 | **刪除** - SFTPGo 安裝目錄 |
|
||||
|
||||
### Step 1: 停止 SFTPGo
|
||||
|
||||
```bash
|
||||
# 找到 SFTPGo 進程
|
||||
ps aux | grep sftpgo | grep -v grep
|
||||
|
||||
# 停止 SFTPGo
|
||||
pkill sftpgo
|
||||
|
||||
# 確認停止
|
||||
ps aux | grep sftpgo | grep -v grep || echo "SFTPGo 已停止"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: 卸載 SFTPGo
|
||||
|
||||
```bash
|
||||
# 卸載 SFTPGo
|
||||
brew uninstall sftpgo
|
||||
|
||||
# 移除 plist
|
||||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.sftpgo.plist
|
||||
sudo rm /Library/LaunchDaemons/com.momentry.sftpgo.plist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3: 刪除專屬檔案
|
||||
|
||||
```bash
|
||||
# 刪除配置目錄 (可選)
|
||||
rm -rf /Users/accusys/momentry/etc/sftpgo
|
||||
|
||||
# 刪除日誌 (可選)
|
||||
rm -f /Users/accusys/momentry/log/sftpgo.log
|
||||
rm -f /Users/accusys/momentry/log/sftpgo.error.log
|
||||
```
|
||||
|
||||
**注意: 不要刪除以下目錄**:
|
||||
```bash
|
||||
# 這些是重要的，不要刪除!
|
||||
# /Users/accusys/momentry/etc/sftpgo
|
||||
# /Users/accusys/momentry/log
|
||||
# /Users/accusys/workspace/sftpgo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4: 卸載後檢查清單
|
||||
|
||||
```bash
|
||||
echo "=== SFTPGo 卸載後檢查 ==="
|
||||
|
||||
# 1. 檢查 SFTPGo 進程
|
||||
echo "1. SFTPGo 進程:"
|
||||
ps aux | grep sftpgo | grep -v grep && echo " ✗ 仍在運行" || echo " ✓ 已停止"
|
||||
|
||||
# 2. Port 8080/2022
|
||||
echo "2. Port 8080/2022:"
|
||||
(lsof -i :8080 > /dev/null 2>&1 || lsof -i :2022 > /dev/null 2>&1) && echo " ✗ 仍被佔用" || echo " ✓ 已釋放"
|
||||
|
||||
# 3. sftpgo 命令
|
||||
echo "3. sftpgo 命令:"
|
||||
which sftpgo > /dev/null 2>&1 && echo " ✗ 仍存在" || echo " ✓ 已移除"
|
||||
|
||||
# 4. brew 安裝
|
||||
echo "4. brew 安裝:"
|
||||
brew list sftpgo > /dev/null 2>&1 && echo " ✗ 仍存在" || echo " ✓ 已移除"
|
||||
|
||||
# 5. launchctl 服務
|
||||
echo "5. launchctl 服務:"
|
||||
sudo launchctl list | grep sftpgo > /dev/null 2>&1 && echo " ✗ 仍存在" || echo " ✓ 已移除"
|
||||
|
||||
# 6. 配置目錄 (可選刪除)
|
||||
echo "6. 配置目錄:"
|
||||
[ -d "/Users/accusys/momentry/etc/sftpgo" ] && echo " ✓ 保留" || echo " ✗ 已刪除"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 手動檢查命令
|
||||
|
||||
```bash
|
||||
# 1. 檢查進程
|
||||
ps aux | grep sftpgo | grep -v grep
|
||||
|
||||
# 2. 檢查 Port
|
||||
lsof -i :8080
|
||||
lsof -i :2022
|
||||
|
||||
# 3. 測試連線
|
||||
curl http://localhost:8080/
|
||||
|
||||
# 4. 查看版本
|
||||
sftpgo --version
|
||||
|
||||
# 5. 驗證配置
|
||||
sftpgo validate --config /Users/accusys/momentry/etc/sftpgo/sftpgo.json
|
||||
|
||||
# 6. 查看日誌
|
||||
tail -20 /Users/accusys/momentry/log/sftpgo.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 連線資訊
|
||||
|
||||
| 項目 | 值 |
|
||||
|------|-----|
|
||||
| HTTP/WebDAV | http://localhost:8080 |
|
||||
| SFTP | localhost:2022 |
|
||||
| FTP | localhost:21 |
|
||||
| Admin API | http://localhost:8080/api/v2/info |
|
||||
|
||||
---
|
||||
|
||||
## 環境變數
|
||||
|
||||
在 `.env` 中:
|
||||
|
||||
```env
|
||||
SFTPGO_CONFIG=/Users/accusys/momentry/etc/sftpgo/sftpgo.json
|
||||
SFTPGO_DATA_DIR=/Users/accusys/workspace/sftpgo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
### SFTPGo 無法啟動
|
||||
|
||||
```bash
|
||||
# 檢查日誌
|
||||
tail -f /Users/accusys/momentry/log/sftpgo.log
|
||||
|
||||
# 驗證配置語法
|
||||
sftpgo validate --config /Users/accusys/momentry/etc/sftpgo/sftpgo.json
|
||||
|
||||
# 檢查目錄權限
|
||||
ls -la /Users/accusys/momentry/etc/sftpgo/
|
||||
|
||||
# 重新設定權限
|
||||
chown -R $(whoami):staff /Users/accusys/momentry/etc/sftpgo
|
||||
```
|
||||
|
||||
### Port 被佔用
|
||||
|
||||
```bash
|
||||
# 檢查哪個程序佔用 port
|
||||
lsof -i :8080
|
||||
lsof -i :2022
|
||||
|
||||
# 終止佔用程序
|
||||
kill <PID>
|
||||
```
|
||||
|
||||
### 需要重新載入 plist
|
||||
|
||||
```bash
|
||||
# 卸載舊服務 (如果存在)
|
||||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.sftpgo.plist 2>/dev/null
|
||||
|
||||
# 載入新服務
|
||||
sudo launchctl load /Library/LaunchDaemons/com.momentry.sftpgo.plist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 檔案位置
|
||||
|
||||
| 類型 | 路徑 | 說明 |
|
||||
|------|------|------|
|
||||
| 安裝 | `/opt/homebrew/opt/sftpgo/` | SFTPGo 安裝目錄 |
|
||||
| 執行檔 | `/opt/homebrew/opt/sftpgo/bin/sftpgo` | SFTPGo 執行檔 |
|
||||
| 配置 | `/Users/accusys/momentry/etc/sftpgo/sftpgo.json` | 設定檔 |
|
||||
| 日誌 | `/Users/accusys/momentry/log/sftpgo.log` | 執行日誌 |
|
||||
| 錯誤日誌 | `/Users/accusys/momentry/log/sftpgo.error.log` | 錯誤日誌 |
|
||||
| 工作目錄 | `/Users/accusys/workspace/sftpgo/` | 上傳檔案目錄 |
|
||||
| plist | `/Library/LaunchDaemons/com.momentry.sftpgo.plist` | 開機啟動 |
|
||||
| 備份 | `/Users/accusys/momentry/var/sftpgo_backup/sftpgo.json` | 配置備份 |
|
||||
|
||||
---
|
||||
|
||||
## 常用指令
|
||||
|
||||
```bash
|
||||
# 驗證配置
|
||||
sftpgo validate --config /Users/accusys/momentry/etc/sftpgo/sftpgo.json
|
||||
|
||||
# 查看版本
|
||||
sftpgo --version
|
||||
|
||||
# 查看可用命令
|
||||
sftpgo --help
|
||||
|
||||
# 重載配置 (熱重載)
|
||||
sftpgo reload --config /Users/accusys/momentry/etc/sftpgo/sftpgo.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 版本資訊
|
||||
|
||||
- 版本: 2.7.0
|
||||
- HTTP Port: 8080
|
||||
- SFTP Port: 2022
|
||||
- FTP Port: 21
|
||||
- 配置: /Users/accusys/momentry/etc/sftpgo/sftpgo.json
|
||||
- 工作目錄: /Users/accusys/workspace/sftpgo
|
||||
- 日誌目錄: /Users/accusys/momentry/log/
|
||||
+6
-138
@@ -1,30 +1,10 @@
|
||||
---
|
||||
document_type: "architecture_design"
|
||||
service: "MOMENTRY_CORE"
|
||||
title: "Job Worker 實作計畫"
|
||||
date: "2026-04-27"
|
||||
version: "V1.2"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "OpenCode"
|
||||
tags:
|
||||
- "實作計畫"
|
||||
- "worker"
|
||||
- "processing_status"
|
||||
ai_query_hints:
|
||||
- "查詢 Job Worker 實作計畫 的內容"
|
||||
- "Job Worker 實作計畫 的主要目的是什麼？"
|
||||
- "如何操作或實施 Job Worker 實作計畫？"
|
||||
- "processing_status 字段設計"
|
||||
---
|
||||
|
||||
# Job Worker 實作計畫
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren / OpenCode |
|
||||
| 建立時間 | 2026-03-24 |
|
||||
| 文件版本 | V1.2 |
|
||||
| 文件版本 | V1.1 |
|
||||
| 狀態 | ✅ 已實作 |
|
||||
|
||||
---
|
||||
@@ -35,7 +15,6 @@ ai_query_hints:
|
||||
|------|------|------|--------|
|
||||
| V1.0 | 2026-03-24 | 建立實作計畫 | OpenCode |
|
||||
| V1.1 | 2026-03-25 | 實作完成，更新狀態 | OpenCode |
|
||||
| V1.2 | 2026-04-27 | 添加 processing_status 字段設計說明 | OpenCode |
|
||||
|
||||
---
|
||||
|
||||
@@ -653,11 +632,11 @@ export REDIS_URL=redis://:accusys@localhost:6379
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `docs_v1.0/OPERATIONS/MOMENTRY_CORE_MONITORING.md` | 監控系統規範 |
|
||||
| `docs_v1.0/REFERENCE/MOMENTRY_CORE_REDIS_KEYS.md` | Redis Key 設計 |
|
||||
| `docs_v1.0/ARCHITECTURE/PROCESSING_PIPELINE.md` | 處理流程 |
|
||||
| `docs_v1.0/ARCHITECTURE/CHUNK_DESIGN.md` | 資料庫設計 |
|
||||
| `docs_v1.0/REFERENCE/API_REFERENCE.md` | API 參考 |
|
||||
| `docs/MOMENTRY_CORE_MONITORING.md` | 監控系統規範 |
|
||||
| `docs/MOMENTRY_CORE_REDIS_KEYS.md` | Redis Key 設計 |
|
||||
| `docs/PROCESSING_PIPELINE.md` | 處理流程 |
|
||||
| `docs/CHUNK_DESIGN.md` | 資料庫設計 |
|
||||
| `docs/API_REFERENCE.md` | API 參考 |
|
||||
|
||||
---
|
||||
|
||||
@@ -692,117 +671,6 @@ export REDIS_URL=redis://:accusys@localhost:6379
|
||||
| `completed` | 所有處理完成 |
|
||||
| `failed` | 處理失敗 |
|
||||
|
||||
### B.1 videos 表 processing_status 欄位
|
||||
|
||||
| 值 | 說明 | 適用場景 |
|
||||
|------|------|----------|
|
||||
| `REGISTERED` | 已註冊 | 新註冊的視頻，尚未觸發處理 |
|
||||
| `PENDING` | 等待處理 | 已觸發處理，等待作業分配 |
|
||||
| `PROBING` | 探測中 | ffprobe 分析執行中 |
|
||||
| `ASR` | ASR 處理中 | ASR 作業執行中 |
|
||||
| `OCR` | OCR 處理中 | OCR 作業執行中 |
|
||||
| `YOLO` | YOLO 處理中 | YOLO 作業執行中 |
|
||||
| `FACE` | 人臉偵測中 | Face 作業執行中 |
|
||||
| `POSE` | 姿態估計中 | Pose 作業執行中 |
|
||||
| `CUT` | 分塊處理中 | Cut 作業執行中 |
|
||||
| `ASRX` | 說話者分離中 | ASRX 作業執行中 |
|
||||
| `COMPLETED` | 完成 | 所有處理完成 |
|
||||
| `FAILED` | 失敗 | 處理失敗 |
|
||||
| `PAUSED` | 暫停 | 斷點續傳暫停狀態 |
|
||||
| `RESUMING` | 恢復中 | 斷點續傳恢復中 |
|
||||
|
||||
#### B.1.1 status 與 processing_status 的關係
|
||||
|
||||
| status | processing_status | 說明 |
|
||||
|--------|-------------------|------|
|
||||
| `pending` | `REGISTERED` | 新註冊，Portal顯示「已註冊」（藍色） |
|
||||
| `processing` | `PENDING` | 已觸發，Portal顯示「等待處理」（黃色） |
|
||||
| `processing` | `PROBING`/`ASR`/... | 各處理器執行中，Portal顯示處理器名稱（靛藍） |
|
||||
| `completed` | `COMPLETED` | 完成，Portal顯示「已完成」（綠色） |
|
||||
| `failed` | `FAILED` | 失敗，Portal顯示「處理失敗」（紅色） |
|
||||
|
||||
#### B.1.2 Portal顯示優先級
|
||||
|
||||
Portal 優先使用 `processing_status`（詳細狀態），Fallback 使用 `status`（基本狀態）。
|
||||
|
||||
#### B.1.3 processing_status JSONB 結構（V1.2 起）
|
||||
|
||||
從 V1.2 起，`processing_status` 改為 **JSONB** 格式，支持多層級進度追蹤。
|
||||
|
||||
詳細規範請參考: `REFERENCE/PROCESSING_STATUS_JSONB_SPEC.md`
|
||||
|
||||
##### JSONB 主要字段
|
||||
|
||||
| 字段 | 類型 | 說明 |
|
||||
|------|------|------|
|
||||
| `phase` | String | 當前階段（PROCESSING, COMPLETED, FAILED） |
|
||||
| `active_processors` | Array[String] | 正在執行的處理器列表（大寫） |
|
||||
| `total_frames` | Integer | 影片總帧數 |
|
||||
| `processing_summary` | Object | 處理器完成狀態總覽 |
|
||||
| `pre_chunks_summary` | Object | pre_chunks 表絕計（按處理器） |
|
||||
| `chunks_summary` | Object | chunks 表絕計（按 Rule） |
|
||||
| `agents` | Object | Agent 任務狀態（5W1H, Translation） |
|
||||
| `vectorization_summary` | Object | 向量化絕計 |
|
||||
| `progress` | Object | 各處理器詳細進度 |
|
||||
|
||||
##### JSONB 範例（處理中）
|
||||
|
||||
```json
|
||||
{
|
||||
"phase": "PROCESSING",
|
||||
"active_processors": ["YOLO", "OCR"],
|
||||
"total_frames": 412343,
|
||||
"progress": {
|
||||
"YOLO": {
|
||||
"current_frame": 25000,
|
||||
"percentage": 6.0,
|
||||
"status": "running"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### JSONB 範例（完成）
|
||||
|
||||
```json
|
||||
{
|
||||
"phase": "COMPLETED",
|
||||
"active_processors": [],
|
||||
"pre_chunks_summary": {
|
||||
"total_records": 25000,
|
||||
"by_processor": {
|
||||
"asr": {"records": 1466},
|
||||
"yolo": {"records": 11000}
|
||||
}
|
||||
},
|
||||
"chunks_summary": {
|
||||
"total_chunks": 2798,
|
||||
"by_rule": {
|
||||
"rule_1": {"chunks_count": 1466},
|
||||
"rule_3": {"chunks_count": 1332}
|
||||
}
|
||||
},
|
||||
"agents": {
|
||||
"5w1h": {"status": "completed"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### SQL 查詢範例
|
||||
|
||||
```sql
|
||||
-- 取得 phase
|
||||
SELECT processing_status->>'phase' FROM videos WHERE uuid = 'xxx';
|
||||
|
||||
-- 取得 active_processors
|
||||
SELECT processing_status->'active_processors' FROM videos WHERE uuid = 'xxx';
|
||||
|
||||
-- 取得 pre_chunks 絕計
|
||||
SELECT processing_status->'pre_chunks_summary'->>'total_records' FROM videos;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### C. processor_results 表 status 欄位
|
||||
|
||||
| 值 | 說明 |
|
||||
@@ -1,40 +1,5 @@
|
||||
---
|
||||
document_type: "reference_doc"
|
||||
service: "MOMENTRY_CORE"
|
||||
title: "Momentry JSON 輸出檔案規範"
|
||||
date: "2026-03-16"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "OpenCode"
|
||||
tags:
|
||||
- "momentry"
|
||||
- "json"
|
||||
- "輸出檔案規範"
|
||||
ai_query_hints:
|
||||
- "查詢 Momentry JSON 輸出檔案規範 的內容"
|
||||
- "Momentry JSON 輸出檔案規範 的主要目的是什麼？"
|
||||
- "如何操作或實施 Momentry JSON 輸出檔案規範？"
|
||||
---
|
||||
|
||||
# Momentry JSON 輸出檔案規範
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-16 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
本文檔定義 Momentry Core 系統中所有 JSON 輸出檔案的結構、命名規範與儲存位置。
|
||||
|
||||
---
|
||||
@@ -1,50 +0,0 @@
|
||||
# M4 / M5 協作協議
|
||||
|
||||
## 核心原則：檔案是 source of truth
|
||||
|
||||
所有 processor 的產出是 `{uuid}.{processor}.json` 檔案。
|
||||
**檔案存在 = 處理完成**，優先於 DB 或 Redis 的任何狀態記錄。
|
||||
|
||||
## 絕對禁止
|
||||
|
||||
### 1. 不可刪除已存在的輸出檔
|
||||
- 任何 `{uuid}.{processor}.*` 檔案，無論是 `.json`、`.json.tmp`、`.json.partial`、`.json.err`
|
||||
- 一律不允許 `rm`、`unlink`、`delete`
|
||||
- 唯一例外：明確的人工指令 `rm` / `Delete this file`
|
||||
|
||||
### 2. 不可覆蓋已存在的輸出檔
|
||||
- 重新執行 processor 前，必須先 **copy（非 rename）** 加上時間戳備份
|
||||
- 備份命名：`{uuid}.{processor}.{timestamp}.{original_extension}`
|
||||
- 若備份名已存在，跳過（不覆蓋不 counter）
|
||||
- 原檔保留不動
|
||||
|
||||
### 3. 不可跨域操作
|
||||
- M4 只能在 M4 機器（Mac Mini）上操作
|
||||
- M5 只能在 M5 機器（MacBook Pro）上操作
|
||||
- 禁止任何跨機器的檔案操作或 cleanup
|
||||
|
||||
## 重跑 processor 的正確流程
|
||||
|
||||
1. Worker 檢查 `{uuid}.{processor}.json` 是否存在
|
||||
2. **存在 → 跳過**（無論 DB/Redis 狀態）
|
||||
3. 不存在 → copy 備份既有 `{uuid}.{processor}.*` → 執行 processor
|
||||
4. Processor 輸出寫入 `.tmp` → 完成後 rename 為 `.json`
|
||||
|
||||
## 例外處理
|
||||
|
||||
| 狀態 | 行為 |
|
||||
|------|------|
|
||||
| `.json` 存在 | 跳過，視為完成 |
|
||||
| `.json.tmp` 存在（無 `.json`） | 視為未完成，備份後重跑 |
|
||||
| `.json.partial` 存在（無 `.json`） | 視為未完成，備份後重跑 |
|
||||
| `.json.err` 存在（無 `.json`） | 視為未完成，備份後重跑 |
|
||||
| Process 被 kill（SIGKILL） | partial 存為 `.json.partial`（非 `.json`） |
|
||||
|
||||
## 違規後果
|
||||
|
||||
2026-05-09 事故：M4 release 打包未含 .json → 跨域操作 → M5 cleanup 誤刪 asr.json
|
||||
→ 導致 ASR 需重跑（完整電影約 1.5hr）
|
||||
→ YOLO 需重跑
|
||||
→ 損失已完成的 pipeline 進度
|
||||
|
||||
此類違規不可再發生。
|
||||
@@ -1,31 +0,0 @@
|
||||
# M4 Release Incident — 2026-05-09
|
||||
|
||||
## Summary
|
||||
|
||||
M4 在進行 release 打包作業時，未依照計畫包含 output `.json` 檔案，僅在 database 中保留 records。此外 M4 違反操作邊界進入 M5 管轄範圍，M5 執行 cleanup 時將已完成的 `asr.json` 一併刪除。
|
||||
|
||||
## Impact
|
||||
|
||||
| 檔案 | 狀態 | 說明 |
|
||||
|------|------|------|
|
||||
| `{uuid}.asr.json` | ❌ 遺失 | 已完成的 ASR 輸出被 M5 cleanup 誤刪 |
|
||||
| `{uuid}.yolo.json` | ❌ 損毀 | JSON parse error，需重跑 |
|
||||
| DB records | ⚠️ 不一致 | processor_results 狀態與實際檔案不符 |
|
||||
|
||||
## Root Cause
|
||||
|
||||
1. **M4 release 打包遺漏**: Release 流程未將 `.json` 輸出檔納入打包範圍，只保留了 DB。
|
||||
2. **M4 越界操作**: M4 在 M5 的目錄/範圍內執行操作，違反開發隔離原則。
|
||||
3. **M5 cleanup 誤刪**: M5 的 cleanup 機制未預期 M4 的產出，將 `asr.json` 視為無用檔案清除。
|
||||
|
||||
## 處理
|
||||
|
||||
- ASR: 重跑中（asr_processor.py，完整電影約 6780s）
|
||||
- YOLO: 重跑中（yolo_processor.py）
|
||||
- 已修改 worker 邏輯：開機後以 `.json` 檔案存在為 source of truth，不再僅依賴 DB/Redis 狀態
|
||||
|
||||
## 預防措施
|
||||
|
||||
- Release 流程需明確定義 deliverables 包含 `.json` 檔案
|
||||
- M4/M5 操作邊界需嚴格遵守，禁止跨域操作
|
||||
- Cleanup 機制應先確認檔案是否為有效 processor output
|
||||
@@ -1,77 +0,0 @@
|
||||
# M4 vs M5 Max Comparison
|
||||
|
||||
## Hardware
|
||||
|
||||
| Spec | M4 (Mac Mini) | M5 (MacBook Pro) |
|
||||
|------|--------------|-------------------|
|
||||
| **Model** | Mac Mini (M4) | MacBook Pro (M5 Max) |
|
||||
| **Hostname** | `accusys-Mac-mini-M4-2.local` | `Accusyss-MacBook-Pro.local` |
|
||||
| **macOS** | 26.4.1 (Sequoia) | 26.4.1 (Sequoia) |
|
||||
| **RAM** | 16 GB | **48 GB** |
|
||||
| **CPU Cores** | 10 | **18** |
|
||||
| **Disk** | 2TB (est.) | **1.8TB (12GB used, 97% free)** |
|
||||
| **Network** | 192.168.110.210, 192.168.110.200 | 192.168.110.201, 192.168.31.182 |
|
||||
|
||||
## Installed Services
|
||||
|
||||
| Service | M4 | M5 |
|
||||
|---------|-----|------|
|
||||
| **PostgreSQL** | 18.1 (Homebrew) | **18.3 (Source build)** |
|
||||
| **pgvector** | Homebrew | **0.8.2 (Source build)** |
|
||||
| **Redis** | 8.4.0 (Homebrew) | **7.4.3 (Source build)** |
|
||||
| **Qdrant** | Homebrew/pre-built | **1.17.1 (Source build, `cargo`)** |
|
||||
| **MongoDB** | Homebrew | 8.2.7 (Homebrew) |
|
||||
| **MariaDB** | ✗ via brew | **12.2.2 (Homebrew, for WordPress)** |
|
||||
| **PHP** | ✗ via brew | **8.5.5 (Homebrew, WordPress ext. ✅)** |
|
||||
| **SFTPGo** | Pre-built binary | **2.7.1 (Source build, patched dep)** |
|
||||
| **FFmpeg** | 8.1 (Homebrew) | **8.1.1 (Homebrew)** |
|
||||
| **OpenCode** | 1.14.39 | **1.14.39** |
|
||||
| **Gemma4 LLM** | ✗ (not enough RAM) | **31B Q5_K_M @ 8081** |
|
||||
|
||||
## Build Approach
|
||||
|
||||
| Aspect | M4 | M5 |
|
||||
|--------|-----|-----|
|
||||
| **PostgreSQL** | `brew install postgresql@18` | `./configure && make && make install` |
|
||||
| **Redis** | `brew install redis` | `make && cp src/redis-server ~/redis/bin/` |
|
||||
| **Qdrant** | `brew install qdrant` | `cargo build --release --bin qdrant` (from GitHub) |
|
||||
| **SFTPGo** | `brew install sftpgo` | `git clone && go build` (patched `go-m1cpu`) |
|
||||
| **Philosophy** | Mixed (Homebrew + binary) | **Source-first** (GitHub source, checksums recorded) |
|
||||
|
||||
## Data Migration (M4 → M5)
|
||||
|
||||
| Data | Size | Status |
|
||||
|------|------|--------|
|
||||
| **Database (dev schema)** | 837MB dump | ✅ Restored (16 tables) |
|
||||
| **Video file** | 2.2GB | ✅ Transferred |
|
||||
| **output_dev JSON** | 2.9GB (462 files) | ✅ Transferred |
|
||||
| **output JSON** | 65MB (2523 files) | ✅ Transferred |
|
||||
| **Configs** | small | ✅ Transferred |
|
||||
|
||||
## Database Row Counts (M5)
|
||||
|
||||
| Table | Rows |
|
||||
|-------|------|
|
||||
| `pre_chunks` | 494,339 |
|
||||
| `face_detections` | 6,211 |
|
||||
| `tkg_nodes` | 2,414 |
|
||||
| `identity_bindings` | 2,347 |
|
||||
| `tkg_edges` | 1,320 |
|
||||
|
||||
## Key Differences
|
||||
|
||||
### 1. RAM (16GB vs 48GB)
|
||||
- **M4 (16GB)**: Cannot run Gemma4 31B LLM locally. Memory pressure during concurrent pipeline processing.
|
||||
- **M5 (48GB)**: Can run Gemma4 31B (Q5_K_M, ~20GB) + databases + playground simultaneously.
|
||||
|
||||
### 2. Build Philosophy
|
||||
- **M4**: Quick setup via Homebrew bottles (pre-compiled).
|
||||
- **M5**: **Source-first** — every service built from GitHub/official source. `SHA256` checksums recorded. Dependencies patched as needed (SFTPGo `go-m1cpu`).
|
||||
|
||||
### 3. Unique M5 Services
|
||||
- **MariaDB + PHP**: Installed for WordPress/marcom portal development.
|
||||
- **Gemma4 LLM**: Running on port 8081, accessible for RAG/identity clustering.
|
||||
- **OpenCode**: Configured with Gemma4 provider for AI-assisted development.
|
||||
|
||||
### 4. Data Freshness
|
||||
- M5 is a **snapshot** of M4's state at 2026-05-06 (commit `bac6c2d`). Changes made on M4 after sync date must be re-synced.
|
||||
@@ -1,259 +0,0 @@
|
||||
# M5 Dev Environment Setup Log
|
||||
|
||||
**Machine**: M5 MacBook Pro (MacOS 26.4.1, Apple M5 Max, 48GB)
|
||||
**User**: accusys (admin group, sudo with password)
|
||||
**Date**: 2026-05-06
|
||||
**Setup by**: OpenCode
|
||||
|
||||
---
|
||||
|
||||
## 1. Source Code
|
||||
|
||||
| Item | Detail |
|
||||
|------|--------|
|
||||
| Repo | `https://gitea.momentry.ddns.net/warren/momentry_core.git` |
|
||||
| Branch | `main` |
|
||||
| Commit | `bac6c2d` (feat: identity clustering V3.0) |
|
||||
| Sync method | rsync from M4 (192.168.110.210) |
|
||||
| Path | `~/momentry_core_0.1/` |
|
||||
|
||||
---
|
||||
|
||||
## 2. Installed Services
|
||||
|
||||
### 2.1 PostgreSQL 18.3
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Source** | [https://ftp.postgresql.org/pub/source/v18.3/postgresql-18.3.tar.gz](https://ftp.postgresql.org/pub/source/v18.3/postgresql-18.3.tar.gz) |
|
||||
| **GitHub** | [https://github.com/postgresql/postgresql](https://github.com/postgresql/postgresql) |
|
||||
| **Build method** | Manual `./configure && make && make install` |
|
||||
| **Prefix** | `~/pgsql/18.3/` |
|
||||
| **Data dir** | `~/pgsql/data/` |
|
||||
| **Port** | 5432 |
|
||||
| **Version** | PostgreSQL 18.3 |
|
||||
| **SHA256** | `ab04939aafdb9e8487c2f13dda91e6a4a7f4c83368f5bedd23ee4ad1fda64afb` |
|
||||
| **Start command** | `pg_ctl -D ~/pgsql/data -l ~/pgsql/pg.log start` |
|
||||
| **Configure flags** | `--prefix=$HOME/pgsql/18.3 --with-uuid=e2fs --with-icu --with-openssl` |
|
||||
| **Build date** | 2026-05-06 |
|
||||
| **Notes** | `--with-uuid=e2fs` used (requires Homebrew `e2fsprogs`). macOS built-in UUID not detected by configure. |
|
||||
|
||||
### 2.2 pgvector 0.8.2
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Source** | [https://github.com/pgvector/pgvector](https://github.com/pgvector/pgvector) |
|
||||
| **Version** | v0.8.2 |
|
||||
| **Build method** | `git clone && make && make install` |
|
||||
| **SHA256** | `65dec31ec078d60ee9d8e1dac59be8a41edf8c79bf380cd0093691b0afd257a8` |
|
||||
| **Build date** | 2026-05-06 |
|
||||
| **Notes** | Built against PostgreSQL 18.3 source installation |
|
||||
|
||||
### 2.3 Redis 7.4.3
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Source** | [https://github.com/redis/redis/archive/refs/tags/7.4.3.tar.gz](https://github.com/redis/redis/archive/refs/tags/7.4.3.tar.gz) |
|
||||
| **GitHub** | [https://github.com/redis/redis](https://github.com/redis/redis) |
|
||||
| **Version** | 7.4.3 |
|
||||
| **Build method** | `make -j$(sysctl -n hw.ncpu)` |
|
||||
| **Binary path** | `~/redis/bin/redis-server` |
|
||||
| **Port** | 6379 |
|
||||
| **SHA256** | `87b6a9ea145c56c1ace724acbb9906b7be4abddd44041545adf44ce9f4d0a615` |
|
||||
| **Start command** | `redis-server --daemonize yes --port 6379` |
|
||||
| **Build date** | 2026-05-06 |
|
||||
|
||||
### 2.4 Qdrant 1.17.1
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Source** | [https://github.com/qdrant/qdrant.git](https://github.com/qdrant/qdrant.git) |
|
||||
| **Version** | v1.17.1 |
|
||||
| **Build method** | `cargo build --release --bin qdrant` |
|
||||
| **Binary path** | `~/momentry_core_0.1/services/qdrant/target/release/qdrant` |
|
||||
| **Storage dir** | `~/qdrant_storage` |
|
||||
| **Port** | 6333 (HTTP), 6334 (gRPC) |
|
||||
| **SHA256** | `8f8aa63840a0f948b43f9b95f784ace69595892de5dc581bb66bd62fd86d6c66` |
|
||||
| **Build date** | 2026-05-06 |
|
||||
| **Config** | `~/qdrant_config.yaml` |
|
||||
| **Start command** | `qdrant --config-path ~/qdrant_config.yaml &` |
|
||||
| **Build deps** | protoc (Homebrew protobuf), cmake |
|
||||
|
||||
### 2.5 MongoDB 8.2.7
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Source** | Homebrew `mongodb/brew/mongodb-community` |
|
||||
| **Version** | 8.2.7 |
|
||||
| **Port** | 27017 |
|
||||
| **Start command** | `brew services start mongodb/brew/mongodb-community` |
|
||||
| **Install date** | 2026-05-06 |
|
||||
|
||||
### 2.6 MariaDB 12.2.2
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Source** | Homebrew `mariadb` |
|
||||
| **Version** | 12.2.2-MariaDB |
|
||||
| **Port** | 3306 |
|
||||
| **Start command** | `brew services start mariadb` |
|
||||
| **Install date** | 2026-05-06 |
|
||||
|
||||
### 2.7 PHP 8.5.5
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Source** | Homebrew `php` |
|
||||
| **Version** | 8.5.5 |
|
||||
| **WordPress extensions** | mysqli, pdo_mysql, gd, xml, mbstring, curl, zip, json, intl, bcmath, gmp, openssl |
|
||||
| **Start command** | `brew services start php` |
|
||||
| **Install date** | 2026-05-06 |
|
||||
|
||||
### 2.8 FFmpeg / FFprobe 8.1.1
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Source** | Homebrew `ffmpeg` |
|
||||
| **Version** | 8.1.1 |
|
||||
| **SHA256** | `00d01197255300c02122c783dd0126a9e7f47d6c6a19faafae2e6610efd071d3` |
|
||||
| **Install date** | 2026-05-06 |
|
||||
|
||||
### 2.9 SFTPGo 2.7.1
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Source** | [https://github.com/drakkan/sftpgo.git](https://github.com/drakkan/sftpgo.git) |
|
||||
| **Version** | v2.7.1 |
|
||||
| **Build method** | `git clone && go build -o sftpgo_bin ./` |
|
||||
| **Binary path** | `~/momentry_core_0.1/services/sftpgo_bin` |
|
||||
| **SHA256** | `550b6653f8f2cd7c58620e128e85be571a6702c79cf374824ad9b420ca039db1` |
|
||||
| **Build date** | 2026-05-06 |
|
||||
| **Patch** | Upgraded `go-m1cpu` from v0.2.0 → v0.2.1 to fix SIGTRAP crash on macOS 26.4.1 |
|
||||
| **Notes** | Pre-built binary from GitHub releases crashed with `go-m1cpu` cgo compatibility issue. Source build with patched dependency resolved. |
|
||||
|
||||
### 2.10 OpenCode 1.14.39
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Source** | [https://opencode.ai/install](https://opencode.ai/install) |
|
||||
| **Version** | 1.14.39 |
|
||||
| **Binary path** | `~/.opencode/bin/opencode` |
|
||||
| **SHA256** | `def4a786c257bd6a965e46a2b069802496681b9eea20261d7d1b55629af3d1da` |
|
||||
| **Install date** | 2026-05-06 |
|
||||
|
||||
### 2.11 Python 3.11 + Packages
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Source** | Homebrew `python@3.11` |
|
||||
| **Version** | 3.11.15 |
|
||||
| **Path** | `/opt/homebrew/bin/python3.11` |
|
||||
| **Key packages** | coremltools, opencv-python, numpy, psycopg2, torch, transformers, whisperx, etc. |
|
||||
| **Requirements** | `~/momentry_core_0.1/requirements.txt` |
|
||||
| **Install date** | 2026-05-06 |
|
||||
| **FaceNet model** | `models/facenet512.mlpackage` (512D CoreML, loads OK) |
|
||||
|
||||
### 2.12 Build Tools
|
||||
|
||||
| Tool | Version | Source |
|
||||
|------|---------|--------|
|
||||
| Rust | 1.95.0 | rustup (pre-installed) |
|
||||
| Go | 1.26.2 | Homebrew `go` |
|
||||
| cmake | 4.3.2 | Homebrew `cmake` |
|
||||
| pkg-config | - | Homebrew `pkg-config` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Momentry Configuration
|
||||
|
||||
### 3.1 Environment Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `.env` | Production config (port 3002) |
|
||||
| `.env.development` | Development config (port 3003) |
|
||||
|
||||
Key settings:
|
||||
- `DATABASE_URL=postgres://accusys@localhost:5432/momentry`
|
||||
- `REDIS_URL=redis://:accusys@localhost:6379`
|
||||
- `DATABASE_SCHEMA=dev`
|
||||
- `MOMENTRY_SERVER_PORT=3003` (dev) / `3002` (prod)
|
||||
- `MOMENTRY_API_KEY=muser_test_apikey`
|
||||
- `MOMENTRY_PYTHON_PATH=/opt/homebrew/bin/python3.11`
|
||||
- `MOMENTRY_SCRIPTS_DIR=/Users/accusys/momentry_core_0.1/scripts`
|
||||
|
||||
### 3.2 Database Tables Created
|
||||
|
||||
| Table | Created by |
|
||||
|-------|-----------|
|
||||
| `dev.videos` | Manual SQL |
|
||||
| `dev.chunks` | Manual SQL |
|
||||
| `dev.monitor_jobs` | Manual SQL |
|
||||
| `dev.processor_results` | Manual SQL |
|
||||
| `dev.talents` | Manual SQL |
|
||||
| `dev.identity_bindings` | Manual SQL |
|
||||
| `dev.api_keys` | Manual SQL |
|
||||
|
||||
### 3.3 API Key
|
||||
|
||||
- Key: `muser_test_apikey`
|
||||
- Hash (SHA256): `3f2fa16e44ff74267786fdf979b9c33dac0cad515282e4937a0776756a61e821`
|
||||
- Status: active
|
||||
|
||||
---
|
||||
|
||||
## 4. Running Services (Verified)
|
||||
|
||||
| Service | Port | Status |
|
||||
|---------|------|--------|
|
||||
| PostgreSQL | 5432 | ✅ |
|
||||
| Redis | 6379 | ✅ |
|
||||
| Qdrant | 6333 | ✅ |
|
||||
| MongoDB | 27017 | ✅ |
|
||||
| MariaDB | 3306 | ✅ |
|
||||
| Momentry Playground | 3003 | ✅ |
|
||||
| Gemma4 LLM | 8081 | ✅ (pre-installed) |
|
||||
|
||||
---
|
||||
|
||||
## 5. PATH Configuration
|
||||
|
||||
`.zshrc`:
|
||||
```zsh
|
||||
export PATH="/opt/homebrew/bin:/opt/homebrew/opt/postgresql@18/bin:$HOME/.opencode/bin:$PATH"
|
||||
```
|
||||
|
||||
Also available:
|
||||
- `$HOME/pgsql/18.3/bin` — source-built PostgreSQL tools
|
||||
- `$HOME/redis/bin` — source-built Redis
|
||||
- `$HOME/.cargo/bin` — Rust/Cargo tools
|
||||
|
||||
---
|
||||
|
||||
## 6. M5 End-to-End Test Results (Charade Full Movie)
|
||||
|
||||
Run date: 2026-05-06 20:38-20:57
|
||||
|
||||
| Stage | Time | Result |
|
||||
|-------|------|--------|
|
||||
| **Swift_face** (Vision ANE detection) | 867s (14.5 min) | 3999 frames (interval=30) |
|
||||
| **CoreML FaceNet** (512D embedding) | 271s (4.5 min) | 6186 face embeddings |
|
||||
| **Face tracker** (scene-cut aware) | ~30s | 1538 traces |
|
||||
| **DB store** | ~5s | 6186 detections in `dev.face_detections` |
|
||||
| **Total** | ~19 min | 1 long video (412k frames, 2.2GB) |
|
||||
|
||||
**Scene-cut effect**: 1538 traces (vs 379 without scene-cut reset in M4 data). Scene boundaries correctly split traces.
|
||||
|
||||
**Models used**:
|
||||
- Face detection: Apple Vision (ANE) via `swift_face`
|
||||
- Face embedding: CoreML FaceNet 512D via `facenet512.mlpackage`
|
||||
- Text embedding: `mxbai-embed-large` (1024D) via Ollama
|
||||
|
||||
---
|
||||
|
||||
## 7. Known Issues
|
||||
|
||||
1. **Momentry API status `degraded`**: Expected on fresh setup. Some cache/processing dependencies not fully initialized.
|
||||
2. **SFTPGo startup requires config**: Binary built from source, needs config file for production use.
|
||||
3. **Migration scripts not all run**: Base tables created manually. Some migration files (017+) reference tables/columns that need verification.
|
||||
4. **OpenCode config**: `~/.config/opencode/config.json` not yet configured for M5 Gemma4 provider.
|
||||
+5
-24
@@ -1,22 +1,3 @@
|
||||
---
|
||||
document_type: "operation_doc"
|
||||
service: "MOMENTRY_CORE"
|
||||
title: "Momentry Core 監控規範 (暫定)"
|
||||
date: "2026-03-17"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "OpenCode"
|
||||
tags:
|
||||
- "momentry"
|
||||
- "core"
|
||||
- "監控規範"
|
||||
ai_query_hints:
|
||||
- "查詢 Momentry Core 監控規範 (暫定) 的內容"
|
||||
- "Momentry Core 監控規範 (暫定) 的主要目的是什麼？"
|
||||
- "如何操作或實施 Momentry Core 監控規範 (暫定)？"
|
||||
---
|
||||
|
||||
# Momentry Core 監控規範 (暫定)
|
||||
|
||||
| 項目 | 內容 |
|
||||
@@ -660,20 +641,20 @@ redis-cli HGETALL momentry:job:{uuid}
|
||||
### 已完成實作 (2026-03-22)
|
||||
|
||||
**監控系統**:
|
||||
- 完整健康檢查腳本設計: `docs_v1.0/OPERATIONS/MOMENTRY_CORE_MONITORING.md`
|
||||
- 完整健康檢查腳本設計: `docs/MOMENTRY_CORE_MONITORING.md`
|
||||
- 多層次服務監控 (Layer 2: Service, Layer 7: Backup)
|
||||
- Redis Job 監控腳本: `monitor/service/redis_job_monitor.sh`
|
||||
- SFTPGo 特殊監控 (API 認證檢查)
|
||||
|
||||
**SFTPGo 管理**:
|
||||
- 備份還原機制: `backup_all.sh` (第 325-546 行)
|
||||
- API 管理用戶與組 (完整文件於 `docs_v1.0/IMPLEMENTATION/INSTALL_SFTPGO.md`)
|
||||
- API 管理用戶與組 (完整文件於 `docs/INSTALL_SFTPGO.md`)
|
||||
- Hook 自動註冊流程: `/Users/accusys/sftpgo_test/register_hook.sh`
|
||||
- Demo 用戶與組完整測試環境
|
||||
|
||||
**文檔更新**:
|
||||
- `docs_v1.0/IMPLEMENTATION/INSTALL_SFTPGO.md`: 新增備份還原、API管理、Hook配置章節
|
||||
- `docs_v1.0/OPERATIONS/MOMENTRY_CORE_MONITORING.md`: 完善監控規範
|
||||
- `docs/INSTALL_SFTPGO.md`: 新增備份還原、API管理、Hook配置章節
|
||||
- `docs/MOMENTRY_CORE_MONITORING.md`: 完善監控規範
|
||||
|
||||
### 待驗證功能
|
||||
|
||||
@@ -689,5 +670,5 @@ redis-cli HGETALL momentry:job:{uuid}
|
||||
- [監控系統總覽](../monitor/MONITORING.md)
|
||||
- [備份規範](./SERVICE_ADDITION_GUIDE.md)
|
||||
- [SFTPGo 安裝與管理指南](./INSTALL_SFTPGO.md)
|
||||
- [API 參考文件](../docs_v1.0/REFERENCE/API_REFERENCE.md)
|
||||
- [API 參考文件](../docs/API_REFERENCE.md)
|
||||
- [n8n 整合指南](./N8N_INTEGRATION_GUIDE.md)
|
||||
@@ -1,23 +1,3 @@
|
||||
---
|
||||
document_type: "reference_doc"
|
||||
service: "REDIS"
|
||||
title: "Momentry Core Redis Key 設計規範"
|
||||
date: "2026-03-17"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "OpenCode"
|
||||
tags:
|
||||
- "momentry"
|
||||
- "core"
|
||||
- "redis"
|
||||
- "設計規範"
|
||||
ai_query_hints:
|
||||
- "查詢 Momentry Core Redis Key 設計規範 的內容"
|
||||
- "Momentry Core Redis Key 設計規範 的主要目的是什麼？"
|
||||
- "如何操作或實施 Momentry Core Redis Key 設計規範？"
|
||||
---
|
||||
|
||||
# Momentry Core Redis Key 設計規範
|
||||
|
||||
| 項目 | 內容 |
|
||||
@@ -1,38 +1,5 @@
|
||||
---
|
||||
document_type: "reference_doc"
|
||||
service: "MOMENTRY_CORE"
|
||||
title: "Node.js 開發指南"
|
||||
date: "2026-03-16"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "OpenCode"
|
||||
tags:
|
||||
- "開發指南"
|
||||
ai_query_hints:
|
||||
- "查詢 Node.js 開發指南 的內容"
|
||||
- "Node.js 開發指南 的主要目的是什麼？"
|
||||
- "如何操作或實施 Node.js 開發指南？"
|
||||
---
|
||||
|
||||
# Node.js 開發指南
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-16 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明 Momentry 專案中 Node.js 環境的配置、管理與監控。
|
||||
@@ -208,8 +175,7 @@ psql -U accusys -h localhost -d momentry -c "SELECT * FROM node_version_baseline
|
||||
|
||||
| 應用 | Node.js 版本 | 執行路徑 | Port | 狀態 | 說明 |
|
||||
|------|-------------|----------|------|------|------|
|
||||
| n8n | 22.22.1 | /opt/homebrew/opt/node@22/bin/node | 5678/5679 | ✅ 執行中 | 工作流自動化平台 |
|
||||
| markdownlint-cli | 25.x | /opt/homebrew/bin/npm | - | ✅ 已安裝 | Markdown lint 工具 |
|
||||
| n8n | 22.22.1 | /opt/homebrew/opt/node@22/bin/node | 5678/5690 | ✅ 執行中 | 工作流自動化平台 |
|
||||
| - | - | - | - | - | 新增應用請填入此表 |
|
||||
|
||||
---
|
||||
@@ -1,94 +0,0 @@
|
||||
# Non-Human Sound Detection — Tool Selection Report
|
||||
|
||||
**Date:** 2026-05-10
|
||||
**Movie:** Charade (1963), 113 min
|
||||
**Audio:** 16kHz mono WAV
|
||||
**Goal:** Detect non-human sound events (gunshots, impacts, doors, music, etc.)
|
||||
|
||||
## Tested Approaches
|
||||
|
||||
### Approach A: AST AudioSet (HuggingFace)
|
||||
|
||||
| Item | Detail |
|
||||
|------|--------|
|
||||
| Model | `MIT/ast-finetuned-audioset-10-10-0.4593` |
|
||||
| Method | Audio Spectrogram Transformer, fine-tuned on AudioSet-2M (527 classes) |
|
||||
| Dependencies | `transformers`, `torch` ✅ (no torchcodec needed) |
|
||||
| Load time | ~1s on M5 |
|
||||
| Inference time | ~0.5s per 3-second clip (805k params, float32) |
|
||||
| Accuracy | Good — correctly distinguishes speech vs. door vs. music |
|
||||
|
||||
**Test results on Charade:**
|
||||
|
||||
| Time | Energy-based said | AST AudioSet said | Verdict |
|
||||
|------|------------------|-------------------|---------|
|
||||
| 0:10 | — | Environmental noise (26%) | Background noise, plausible |
|
||||
| 10:32 | Gunshot candidate (43x) | **Speech (76%)** | ✅ AST correct |
|
||||
| 57:00 | Gunshot candidate (49x) | **Door (62%) + Slam (5%)** | ✅ AST correct |
|
||||
| 65:13 | Gunshot candidate (50x) | **Speech (58%)** | ✅ AST correct |
|
||||
| 85:12 | Gunshot candidate (39x) | **Speech (68%)** | ✅ AST correct |
|
||||
|
||||
**Conclusion**: Energy-based impulse detection has **100% false positive rate** for gunshot detection. AST AudioSet correctly classifies all candidates as non-gunshot.
|
||||
|
||||
### Approach B: Custom Energy + Spectral Features
|
||||
|
||||
| Item | Detail |
|
||||
|------|--------|
|
||||
| Method | RMS energy + spectral centroid + sub-band energy ratios |
|
||||
| Speed | ~3s for full 113-min movie (every 10th window) |
|
||||
| Accuracy | Poor — cannot distinguish gunshot from speech, door, music |
|
||||
| Result | 1 "gunshot_candidate" from 453 test windows; all false positives on verification |
|
||||
|
||||
**Conclusion**: Useful as a **coarse pre-filter** (Stage 1), not as a standalone classifier.
|
||||
|
||||
## Two-Stage Design
|
||||
|
||||
```
|
||||
Stage 1 (Energy filter, ~1 min):
|
||||
Full audio → sliding window RMS + centroid → ~200 candidate windows
|
||||
|
|
||||
v
|
||||
Stage 2 (AST classifier, ~2 min):
|
||||
Extract 3-sec audio for each candidate → AST AudioSet classification
|
||||
|
|
||||
v
|
||||
Non-speech events: gunshot, explosion, door slam, music, etc.
|
||||
```
|
||||
|
||||
Estimated processing: ~3 min for full movie (vs. 75 min for full AST scan)
|
||||
|
||||
## Key AudioSet Classes Relevant to Charade
|
||||
|
||||
| Class | AudioSet ID | Relevance |
|
||||
|-------|-------------|-----------|
|
||||
| Gunshot, gunfire | 402 | **Primary target** |
|
||||
| Explosion | 400 | Hand grenade in plot |
|
||||
| Door slams | 404 | Scenes at hotel, apartment |
|
||||
| Music | 130-133 | Background score |
|
||||
| Speech | 0-3 | Already handled by ASR |
|
||||
| Vehicle | 100-110 | Car sounds in Paris chase |
|
||||
| Glass break | 424 | Window breaking scene |
|
||||
|
||||
## Actor-voice gender mismatches (resolved by fine-grained ASRX)
|
||||
|
||||
During the speaker mapping work, 20 segments where the old face→TMDb assignment said "Audrey Hepburn" but the new ASRX voice embedding clearly said "MALE". These segments were verified via video clips and confirmed to be scenes where:
|
||||
|
||||
1. A male speaker (Cary Grant or other) is speaking while Audrey Hepburn's face is on screen
|
||||
2. The old pipeline incorrectly assigned the speaker name based on face identity
|
||||
3. The fine-grained sliding window approach correctly resolves these
|
||||
|
||||
The 20 segments were from SPEAKER_5 (10 segs) and SPEAKER_9 (10 segs), both of which mapped to MALE voice clusters. These were re-assigned to "Cary Grant" or "Unknown" as appropriate.
|
||||
|
||||
## Recommendations
|
||||
|
||||
| Approach | Speed | Accuracy | Best for |
|
||||
|----------|-------|----------|----------|
|
||||
| Energy pre-filter | ✅ 1 min | ❌ Low | Stage 1: candidate selection |
|
||||
| AST AudioSet | ⚠️ 2 min | ✅ High | Stage 2: event classification |
|
||||
| Full AST scan | ❌ 75 min | ✅ High | N/A — two-stage is better |
|
||||
|
||||
**Design**: Two-stage pipeline: energy pre-filter → AST classifier
|
||||
**Implementation path**:
|
||||
1. Write `scripts/non_human_sound_detector.py` with the two-stage design
|
||||
2. Output `{uuid}.sound_events.json` with typed events
|
||||
3. Integrate into the sound_event_detector framework
|
||||
@@ -1,150 +0,0 @@
|
||||
# Phase 1 Completion Report — v2 (fine-grained ASRX)
|
||||
|
||||
**File**: Charade (1963) Cary Grant & Audrey Hepburn
|
||||
**UUID**: `aeed71342a899fe4b4c57b7d41bcb692`
|
||||
**Date**: 2026-05-10
|
||||
**System**: M5 (MacBook Pro, 48GB, Apple Silicon)
|
||||
|
||||
---
|
||||
|
||||
## 1. Processor Outputs
|
||||
|
||||
| File | Size | Description |
|
||||
|------|------|-------------|
|
||||
| `asr.json` | 413KB | 3,417 segments, full movie coverage (Whisper small) |
|
||||
| `asrx.json` | **18MB** | **4,188 segments** (fine-grained, ECAPA-TDNN) |
|
||||
| `asrx_fine.json` | 45MB | 4,188 fine segments + voice embeddings (intermediate) |
|
||||
| `cut.json` | 329KB | 2,260 scenes |
|
||||
| `yolo.json` | 181MB | 169,625 frames with object detections |
|
||||
| `face.json` | **106MB** | 4,550 frames, 5,910 faces @ 8Hz (CoreML 512D) |
|
||||
| `face_traced.json` | 110MB | Traced faces with 423 identity traces |
|
||||
| `lip.json` | 492KB | Lip openness analysis |
|
||||
| `ocr.json` | 277KB | 606 OCR frames |
|
||||
| `pose.json` | 26MB | 4,211 pose frames |
|
||||
| `scene.json` | 403B | Scene classification |
|
||||
|
||||
## 2. Pipeline 8-Stage Checklist
|
||||
|
||||
| Stage | Status | Detail |
|
||||
|-------|--------|--------|
|
||||
| ASR | ✅ | 3,417 segments, last end 6,773s (100%) |
|
||||
| ASRX | ✅ | **4,188 segments** (fine-grained, 10→3 speakers mapped) |
|
||||
| Sentence Chunks | ✅ | **4,188 sentence chunks** with yolo_objects + face_ids |
|
||||
| Vectorization | ✅ | 4,188 Qdrant (768D), all 3 collections updated |
|
||||
| Face Trace | ✅ | 423 traces, 11,820 detections @ 8Hz |
|
||||
| TKG Graph | ✅ | 498 nodes, 1,617 edges |
|
||||
| Trace Chunks | ✅ | 423 trace chunks |
|
||||
| Phase 1 Release | ✅ | 3.0GB package |
|
||||
|
||||
## 3. Speaker Identification
|
||||
|
||||
### ASRX Enhancement (3417 → 4188 segments)
|
||||
|
||||
The original Whisper ASR merges rapid back-and-forth dialogue into single segments. A sliding-window ECAPA-TDNN approach was developed to detect speaker change points within each ASR segment:
|
||||
|
||||
1. **Sliding window**: 1.5s window, 0.75s stride across full audio
|
||||
2. **ECAPA-TDNN 192D embedding** per window
|
||||
3. **Classification** against reference centroids (Cary Grant, Audrey Hepburn, Unknown)
|
||||
4. **Majority-vote smoothing** over 3 adjacent windows
|
||||
5. **Change point detection** where classified speaker changes
|
||||
6. **Split** original ASR segment at each change point
|
||||
|
||||
**Result**: 3,417 → **4,188 segments** (+771, +22.6%). Validated via gender classification (ECAPA-TDNN → 92.3% agreement with character identity).
|
||||
|
||||
### Speaker Mapping (Centroid-based)
|
||||
|
||||
| Speaker ID | Name | Segments | Duration | Voice Gender |
|
||||
|------------|------|----------|----------|-------------|
|
||||
| SPEAKER_0 | Audrey Hepburn | 1,658 | 2,786s | FEMALE |
|
||||
| SPEAKER_1 | Cary Grant | 2,033 | 3,962s | MALE |
|
||||
| SPEAKER_2 | Unknown (minor) | 497 | 806s | MIXED |
|
||||
|
||||
Method: Reference centroids built from 3,107 known segments (1,420 Cary + 1,689 Audrey). Each fine segment classified by cosine similarity to nearest centroid. No cross-contamination between speaker clusters.
|
||||
|
||||
### Gender Validation
|
||||
|
||||
Two small clusters (SPEAKER_5: 10 segs, SPEAKER_9: 10 segs) initially showed MALE voice → Audrey assignment. Video clip verification confirmed these are segments where a male voice speaks while Audrey is on screen (old face-based matching was incorrect). The fine-grained segmentation correctly resolves these.
|
||||
|
||||
## 4. Sentence Chunks — Full Migration
|
||||
|
||||
All 4,188 fine segments were written to `dev.chunks` with complete data per chunk:
|
||||
|
||||
| Chunk Field | Value | Source |
|
||||
|-------------|-------|--------|
|
||||
| `start_time`/`end_time` | Fine segment boundaries | `asrx_fine.json` |
|
||||
| `start_frame`/`end_frame` | time × 25fps | Calculated |
|
||||
| `content` | `{data: {text, text_normalized}, rule: rule_1}` | ASR text |
|
||||
| `metadata.yolo_objects` | Dedup class names in frame range | `pre_chunks(yolo)` |
|
||||
| `metadata.face_ids` | Trace IDs in frame range | `face_detections` |
|
||||
| `metadata.speaker_name` | Centroid-matched identity | `asrx_fine.json` |
|
||||
|
||||
- 4,158/4,188 chunks have YOLO objects (avg 3-5 object classes)
|
||||
- 398/4,188 chunks have face IDs (face data covers first ~12 min only)
|
||||
|
||||
### Parent/Story Chunks
|
||||
|
||||
| Metric | Before (v1) | After (v2) |
|
||||
|--------|-------------|------------|
|
||||
| Children per parent | 15 (fixed) | 15 (fixed) |
|
||||
| Total parents | 228 | **280** |
|
||||
| LLM summaries | 228 (Gemma4) | **280** (Gemma4, regenerated) |
|
||||
| Qdrant stories | 456 pts | **560 pts** |
|
||||
|
||||
## 5. Qdrant Vector Collections
|
||||
|
||||
| Collection | Dims | Points | Content | Status |
|
||||
|-----------|------|--------|---------|--------|
|
||||
| `momentry_dev_v1` | 768 | **4,188** | Sentence chunk embeddings (EmbeddingGemma) | ✅ |
|
||||
| `momentry_dev_stories` | 768 | **560** | 280 dialogue + 280 LLM summary | ✅ |
|
||||
| `momentry_dev_faces` | 512 | 5,910 | Face embeddings (8Hz CoreML) | ✅ |
|
||||
| `momentry_dev_voice` | 192 | **4,188** | Voice embeddings (ECAPA-TDNN) | ✅ |
|
||||
| `sentence_story` | 768 | **4,188** | Sentence template with speaker | ✅ |
|
||||
| `sentence_summary` | 768 | **4,188** | Context-aware LLM sentence summary | ✅ |
|
||||
|
||||
## 6. ASR Model Selection
|
||||
|
||||
A comprehensive benchmark (5 models × 2 VAD settings × 3 test clips = 30 runs) showed:
|
||||
|
||||
| Model | Segments | Chars | Runtime | Verdict |
|
||||
|-------|----------|-------|---------|---------|
|
||||
| tiny | 56 avg | 1,730 | **9.2s** | Most segments, best text capture |
|
||||
| **small** | **55 avg** | **1,704** | **17.6s** | **Best balance (current)** |
|
||||
| base | 42 avg | 1,751 | 10.1s | Good but fewer segments |
|
||||
| medium | 52 avg | 1,627 | 339.6s | Slow, loses text |
|
||||
| large-v3 | 20 avg | 1,249 | 68.8s | **Worst**: merges utterances, loses 26% text |
|
||||
|
||||
**Conclusion**: Keep `faster-whisper small (VAD 500ms)`. The missing-text problem is not solvable by model size — even tiny captures more text than large-v3. Root cause is Whisper's lack of speaker turn detection in segment boundary logic, which is solved by the sliding-window ASRX approach above.
|
||||
|
||||
## 7. Release Package
|
||||
|
||||
| Component | Size |
|
||||
|-----------|------|
|
||||
| `output_json/` | 13 processor files |
|
||||
| `chunks.csv` | 3.2MB |
|
||||
| `vectors.csv` | 58MB |
|
||||
| `identities.csv` | 1MB |
|
||||
| `schema.sql` | 30KB |
|
||||
| Qdrant snapshots (5 collections) | ~3GB |
|
||||
| `RELEASE_INFO.txt` | Metadata |
|
||||
| **Total** | **~3.0GB** |
|
||||
|
||||
## 8. Key Technical Decisions
|
||||
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| Sliding window 1.5s/0.75s | Optimal balance: captures turn boundaries without over-splitting |
|
||||
| Centroid-based classification | 0.8+ similarity, no retraining needed, 100% consistent |
|
||||
| Word-timestamp ASR for text | Re-run with `word_timestamps=True`, 87% coverage; remaining 13% → per-segment ASR fallback |
|
||||
| Fixed 15 children/parent | Maintains Phase 1 design consistency |
|
||||
| `yolo_objects` dedup | Only class names stored per chunk (not per-frame) |
|
||||
| `face_ids` via `trace_id` | `face_id` column is NULL in DB; `trace_id` is the actual identifier |
|
||||
| Keep ASR small model | Benchmarked 5 models; larger models lose text, not gain it |
|
||||
| `app.run(threaded=True)` | Dashboard v2: single-threaded Flask was blocking on subprocess calls |
|
||||
|
||||
## 9. Phase 2 Preparation
|
||||
|
||||
Pending for Phase 2:
|
||||
- Rule 3 scene chunking (cut-based parent chunks)
|
||||
- 5W1H Agent (LLM-generated scene summaries)
|
||||
- Full pipeline + 5W1H release packaging
|
||||
- Source separation (Demucs/HPSS) for overlapping speech scenarios
|
||||
@@ -1,63 +0,0 @@
|
||||
# Phase 1 Release Checklist
|
||||
|
||||
**UUID**: `aeed71342a899fe4b4c57b7d41bcb692`
|
||||
**Model**: v2 (fine-grained ASRX, 4,188 segments)
|
||||
**Date**: 2026-05-10
|
||||
|
||||
## 1. Processor Outputs
|
||||
|
||||
- [x] `asr.json` — faster-whisper small, 3,417 segments
|
||||
- [x] `asrx.json` — ECAPA-TDNN fine-grained, 4,188 segments
|
||||
- [x] `cut.json` — 2,260 scene cuts
|
||||
- [x] `yolo.json` — 169,625 frames, object detections
|
||||
- [x] `face.json` — 4,550 frames, 5,910 faces @ 8Hz
|
||||
- [x] `face_traced.json` — 423 traced identities
|
||||
- [x] `lip.json` — Lip openness per ASRX segment
|
||||
- [x] `ocr.json` — 606 OCR frames
|
||||
- [x] `pose.json` — 4,211 pose frames
|
||||
- [x] `scene.json` — Scene classification
|
||||
|
||||
## 2. Pipeline Stages
|
||||
|
||||
- [x] ASR: 3,417 segments, full movie
|
||||
- [x] ASRX: 4,188 segments (fine-grained), 3 speakers
|
||||
- [x] Sentence chunks: 4,188 in `dev.chunks`
|
||||
- [x] Vectorization: 4,188 in Qdrant `momentry_dev_v1`
|
||||
- [x] Face trace: 423 traces, 11,820 detections
|
||||
- [x] TKG: 498 nodes, 1,617 edges
|
||||
- [x] Trace chunks: 423 in `dev.chunks`
|
||||
- [x] All 8 stages passing
|
||||
|
||||
## 3. Qdrant Collections
|
||||
|
||||
- [x] `momentry_dev_v1` — 4,188 pts, 768D (EmbeddingGemma)
|
||||
- [x] `momentry_dev_stories` — 560 pts, 768D (280 dialogue + 280 summary)
|
||||
- [x] `momentry_dev_faces` — 5,910 pts, 512D (CoreML FaceNet)
|
||||
- [x] `momentry_dev_voice` — 4,188 pts, 192D (ECAPA-TDNN)
|
||||
- [x] `sentence_story` — 4,188 pts, 768D (sentence template)
|
||||
- [x] `sentence_summary` — 4,188 pts, 768D (context-aware LLM)
|
||||
|
||||
## 4. Database (dev.chunks)
|
||||
|
||||
- [x] Sentence chunks: 4,188 with speaker_name, speaker_id
|
||||
- [x] Story chunks: 280 with LLM summaries
|
||||
- [x] Cut chunks: 1,130
|
||||
- [x] Trace chunks: 423
|
||||
- [x] YOLO objects in metadata: 4,158/4,188
|
||||
- [x] Face IDs in metadata: 398/4,188
|
||||
- [x] Parent-child relationships set
|
||||
|
||||
## 5. Speaker Mapping
|
||||
|
||||
- [x] SPEAKER_0 → Audrey Hepburn (1,658 segs, gender FEMALE ✅)
|
||||
- [x] SPEAKER_1 → Cary Grant (2,033 segs, gender MALE ✅)
|
||||
- [x] SPEAKER_2 → Unknown (497 segs, minor characters)
|
||||
- [x] Voice embeddings validated via gender classification
|
||||
|
||||
## 6. Release Package
|
||||
|
||||
- [x] Phase 1 release packaged at `release/phase1/latest/`
|
||||
- [x] Qdrant snapshots for all 5 collections
|
||||
- [x] `chunks.csv`, `vectors.csv`, `identities.csv` exported
|
||||
- [x] `schema.sql` from PostgreSQL
|
||||
- [x] Dashboard v2 running at port 5050
|
||||
+2
-38
@@ -1,41 +1,5 @@
|
||||
---
|
||||
document_type: "reference_doc"
|
||||
service: "MOMENTRY_CORE"
|
||||
title: "Playground Binary Implementation Plan"
|
||||
date: "2026-03-23"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "OpenCode"
|
||||
tags:
|
||||
- "binary"
|
||||
- "plan"
|
||||
- "implementation"
|
||||
- "playground"
|
||||
ai_query_hints:
|
||||
- "查詢 Playground Binary Implementation Plan 的內容"
|
||||
- "Playground Binary Implementation Plan 的主要目的是什麼？"
|
||||
- "如何操作或實施 Playground Binary Implementation Plan？"
|
||||
---
|
||||
|
||||
# Playground Binary Implementation Plan
|
||||
|
||||
| Item | Content |
|
||||
|------|---------|
|
||||
| Author | Warren |
|
||||
| Created | 2026-03-23 |
|
||||
| Document Version | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Date | Purpose | Operator | Tool/Model |
|
||||
|---------|------|---------|----------|------------|
|
||||
| V1.0 | 2026-03-23 | Create implementation plan | Warren | OpenCode |
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Create separate `momentry_playground` binary with distinct configuration from `momentry` (production).
|
||||
@@ -399,8 +363,8 @@ momentry_dev:worker:job:{uuid}:processor:{name}
|
||||
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| `docs_v1.0/REFERENCE/SERVICES.md` | Port allocations |
|
||||
| `docs_v1.0/REFERENCE/MOMENTRY_CORE_REDIS_KEYS.md` | Redis key design |
|
||||
| `docs/SERVICES.md` | Port allocations |
|
||||
| `docs/MOMENTRY_CORE_REDIS_KEYS.md` | Redis key design |
|
||||
| `AGENTS.md` | Code style and conventions |
|
||||
|
||||
---
|
||||
@@ -1,134 +0,0 @@
|
||||
# Processor 產出機制檢討
|
||||
|
||||
## 三層機制定義
|
||||
|
||||
### 1. 中斷接續（Interruption Resume）
|
||||
Process 被殺掉後，重啟時能接續進度。
|
||||
**現狀**: 大部分 processor 有 `.tmp` → `.partial` 保護，但重跑時從頭開始。
|
||||
|
||||
### 2. 補充機制（Supplement）
|
||||
完成度不足時，只補沒做完的部分，不重跑整個。
|
||||
**現狀**: 全部從頭跑，無補充。
|
||||
|
||||
### 3. 糾錯機制（Error Correction）
|
||||
輸出檔損毀時能自動偵測並修復。
|
||||
**現狀**: file-existence check 只檢查檔案存在，不檢查內容是否有效。
|
||||
|
||||
---
|
||||
|
||||
## Processor 逐一檢討
|
||||
|
||||
### ASR
|
||||
| 面向 | 現狀 | 問題 |
|
||||
|------|------|------|
|
||||
| 中斷接續 | ✅ `.tmp` → `.partial`（executor） | ✅ OK |
|
||||
| 補充機制 | ❌ 每次從頭跑 | 若跑到 50% 被殺，下次從 0% 開始 |
|
||||
| 糾錯機制 | ❌ 不驗證內容 | file-existence check 看到 `.json` 存在就跳過，不管內容 |
|
||||
| Pipe | ✅ executor.run() | ✅ |
|
||||
| Timeout | ✅ 已移除（None） | ✅ |
|
||||
|
||||
**改善方案**:
|
||||
- 補充：ASR 重跑時掃描 existing `.json` 或 `.partial`，找出最後 segment 的 `end_time`，傳入 `--resume-from` 給 Python script
|
||||
- 糾錯：file-existence check 對 `.json` 做 `serde_json::from_str` 驗證，無效 → 視為不存在
|
||||
|
||||
### ASRX
|
||||
| 面向 | 現狀 | 問題 |
|
||||
|------|------|------|
|
||||
| 中斷接續 | ❌ **不用 executor**，直接寫 `.json` | 被殺掉時留下壞檔 |
|
||||
| 補充機制 | ❌ 同 ASR | 依賴 ASR，ASR 不完整 ASRX 也不能跑 |
|
||||
| 糾錯機制 | ❌ 不驗證內容 | 同上 |
|
||||
| Pipe | ❌ **raw Command**，沒有 `.tmp` 保護 | 緊急 |
|
||||
| Timeout | ⚠️ 7200s hardcode | 應改為 None（同 ASR） |
|
||||
|
||||
**改善方案**:
|
||||
- **最優先**: 改為使用 `executor.run()`，獲得 `.tmp` 保護
|
||||
- 其他同 ASR
|
||||
|
||||
### YOLO
|
||||
| 面向 | 現狀 | 問題 |
|
||||
|------|------|------|
|
||||
| 中斷接續 | ✅ executor `.tmp` | ✅ |
|
||||
| 補充機制 | ❌ 從頭跑 | 若跑到 frame 100,000 被殺，下次從 frame 0 |
|
||||
| 糾錯機制 | ❌ 不驗證內容 | yolo.json 之前就是壞的但 file check 跳過 |
|
||||
|
||||
**改善方案**:
|
||||
- 補充：掃描 `.partial` 的最後 frame，傳入 `--resume-frame` 給 Python script
|
||||
- 糾錯：file-existence check 對 `.json` 做 JSON parse 驗證
|
||||
|
||||
### FACE / POSE / OCR
|
||||
| 面向 | 現狀 | 問題 |
|
||||
|------|------|------|
|
||||
| 中斷接續 | ✅ executor `.tmp` | ✅ |
|
||||
| 補充機制 | ❌ 從頭跑 | 同 YOLO |
|
||||
| 糾錯機制 | ❌ 不驗證內容 | 同 YOLO |
|
||||
|
||||
**改善方案**: 同 YOLO
|
||||
|
||||
### CUT
|
||||
| 面向 | 現狀 | 問題 |
|
||||
|------|------|------|
|
||||
| 中斷接續 | ✅ executor `.tmp` | ✅ |
|
||||
| 補充機制 | ✅ register 階段已完成，直接載入 | ✅ |
|
||||
| 糾錯機制 | ❌ 不驗證內容 | 同 YOLO |
|
||||
|
||||
**改善方案**: 糾錯即可
|
||||
|
||||
### SCENE
|
||||
| 面向 | 現狀 | 問題 |
|
||||
|------|------|------|
|
||||
| 中斷接續 | ✅ **最完整**：檢查 `.err`/`.json`/`.tmp` 三種狀態 | ✅ |
|
||||
| 補充機制 | ❌ 從頭跑 | ✅（scene 很快） |
|
||||
| 糾錯機制 | ⚠️ 有檢查 `.err` | ✅ |
|
||||
|
||||
### VISUAL_CHUNK
|
||||
| 面向 | 現狀 | 問題 |
|
||||
|------|------|------|
|
||||
| 中斷接續 | ✅ executor `.tmp` | ✅ |
|
||||
| 補充機制 | ❌ | ❌ |
|
||||
| 糾錯機制 | ❌ **錯誤被吞掉**（回傳空結果） | 應回報 error 而非靜默失敗 |
|
||||
|
||||
**改善方案**: 不要吞錯誤，讓 error 往上傳
|
||||
|
||||
### STORY
|
||||
| 面向 | 現狀 | 問題 |
|
||||
|------|------|------|
|
||||
| 中斷接續 | ✅ executor `.tmp` | ✅ |
|
||||
| 補充機制 | ❌ | ❌ |
|
||||
| 糾錯機制 | ❌ | ❌ |
|
||||
|
||||
---
|
||||
|
||||
## 優先級
|
||||
|
||||
### P0 — 立即修復
|
||||
|
||||
1. **ASRX 改用 executor.run()**
|
||||
- 檔案：`src/core/processor/asrx.rs`
|
||||
- 獲得 `.tmp` 保護、SIGKILL process group、`.partial` 保留
|
||||
- 移除 hardcode timeout
|
||||
|
||||
### P1 — 糾錯機制
|
||||
|
||||
2. **File-existence check 加入 JSON 驗證**
|
||||
- 檔案：`src/worker/job_worker.rs`
|
||||
- 在 `output_path.exists()` 之後，對 `.json` 做 `serde_json::from_str::<Value>`
|
||||
- 若 parse 失敗 → 不 skip，當作檔案不存在繼續跑
|
||||
- 若 parse 成功但內容空（無 segments/frames）→ 當不完整
|
||||
|
||||
### P2 — 補充機制
|
||||
|
||||
3. **ASR resume-from 補充**
|
||||
- 檔案：`src/core/processor/asr.rs` + `scripts/asr_processor.py`
|
||||
- Rust 端發現 `.partial` 存在，讀取最後 segment 的 end_time
|
||||
- 傳入 `--resume-from {time}` 給 Python script
|
||||
- Python script 跳過 `--resume-from` 之前的音訊
|
||||
|
||||
4. **YOLO/Face/Pose resume-frame 補充**
|
||||
- 檔案：各 processor.rs + 對應 Python script
|
||||
- 掃描 `.partial` 中的最後 frame_number
|
||||
- 傳入 `--resume-frame {frame}` 給 Python script
|
||||
|
||||
### P3 — 其他
|
||||
|
||||
5. **VisualChunk 不吞錯誤**
|
||||
6. **Executor SIGTERM → SIGKILL 兩段式關閉**
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user