admin/momentry_core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: backup architecture docs, source code, and scripts

Browse Source
This commit is contained in:
Warren
2026-04-25 17:15:45 +08:00
parent 59809dae1f
commit 1f84e5469f
368 changed files with 146329 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files

201
docs_v1.0/PROCESSORS/SPECIFICATION/AI_DRIVEN_PROCESSOR_CONTRACT.md Normal file
View File

@@ -0,0 +1,201 @@
---
document_type: "specification"
service: "MOMENTRY_CORE"
title: "AI-Driven Processor Contract"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "ai-processor"
- "contract"
- "standardization"
- "specification"
ai_query_hints:
- "AI Processor Contract 的規範內容是什麼？"
- "如何讓自定義 Processor 符合合約標準？"
- "AI Processor 的標準化介面定義為何？"
---
# AI-Driven Processor Contract
## Overview
This document defines the contract that all AI-driven processors in the Momentry system must follow to ensure consistency, reliability, and maintainability.
## Version
Contract Version: 1.0
Effective Date: 2025-03-27
## Core Principles
1. **Internal Standardization** – Consistent implementation patterns across all processors
2. **External Communication** – Standardized interfaces for integration with other system components
3. **Self-Monitoring** – Built-in health checks and resource monitoring
4. **Graceful Degradation** – Fallback strategies when optimal processing fails
5. **Performance Awareness** – Adherence to performance constraints (≤5% overhead)
## Command-Line Interface
All processors must support the following command-line arguments:
### Required Arguments
- `video_path` – Path to input video file
- `output_path` – Path where JSON output should be written
### Optional Arguments
- `--uuid`, `-u` – UUID for Redis progress reporting (default: empty string)
- `--check-health` – Perform health check and exit (does not process video)
### Hidden/Configuration Arguments (can also be set via environment variables)
- Processor-specific configuration arguments should be hidden from help (`argparse.SUPPRESS`)
- Environment variable names should follow pattern: `MOMENTRY_{PROCESSOR}_*`
## Redis Progress Reporting
Processors must use the `RedisPublisher` class for progress reporting:
### Message Types
- `info` – General information about processing stages
- `progress` – Percentage completion for long-running tasks
- `warning` – Non-fatal issues that don't stop processing
- `error` – Fatal errors that cause processing to stop
- `complete` – Final completion message with summary statistics
### Message Format
```json
{
"type": "info|progress|warning|error|complete",
"processor": "processor_name",
"message": "Human-readable message",
"timestamp": "ISO 8601 timestamp"
}
```
## Signal Handling
Processors must handle the following signals:
- `SIGTERM` – Graceful shutdown request from system
- `SIGINT` – User interrupt (Ctrl+C)
Signal handlers should:
1. Log the signal reception
2. Clean up temporary resources
3. Exit with appropriate exit code
## Health Checks
Processors must implement a health check mode (`--check-health`) that:
1. Verifies all required dependencies are available
2. Checks access to required external services (if any)
3. Returns a JSON structure with status and detailed information
4. Exits with code 0 for healthy, non-zero for unhealthy
Example health check output:
```json
{
"status": "healthy",
"dependencies": {
"faster_whisper": "available",
"psutil": "available"
},
"timestamp": "2025-03-27T10:30:00Z"
}
```
## Resource Monitoring
Processors should monitor their own resource usage during long-running operations:
- Sample CPU and memory usage at configurable intervals (default: 60 seconds)
- Log resource usage via Redis publisher when threshold exceeded
- Implement circuit breakers for excessive resource consumption
## Output JSON Schema
All processors must produce JSON output with the following base structure:
### Required Fields
- `processor_name` – String identifying the processor (e.g., "asr", "yolo")
- `processor_version` – Semantic version of the processor implementation
- `contract_version` – Version of this contract (e.g., "1.0")
### Processor-Specific Fields
- Processor-specific data fields (e.g., `segments` for ASR, `frames` for OCR)
### Optional Metadata
- `processing_mode` – How processing was performed (e.g., "direct", "chunked")
- `chunk_count` – Number of chunks used (for chunked processing)
- `chunk_duration` – Duration of each chunk in seconds
### Example ASR Output
```json
{
"processor_name": "asr",
"processor_version": "2.0.0",
"contract_version": "1.0",
"language": "en",
"language_probability": 0.95,
"segments": [
{
"start": 0.0,
"end": 2.5,
"text": "Hello world"
}
],
"processing_mode": "chunked",
"chunk_count": 7,
"chunk_duration": 600
}
```
## Error Handling
### Graceful Failure
- When processing fails, processors should clean up temporary resources
- Write error information to stderr with clear error messages
- Exit with non-zero exit code
### Fallback Strategies
- Implement fallback processing modes when optimal approach fails (e.g., direct → chunked transcription)
- Document fallback conditions and limitations
## Performance Constraints
### Overhead Limit
- Any optimization or additional functionality must not increase processing time by more than 5%
- Benchmark against baseline implementation to verify compliance
### Timeout Handling
- Respect timeout configurations from system configuration
- Implement progress-based timeout extensions where appropriate
## Checkpointing and Resume (Optional)
For long-running processors (> 5 minutes):
- Implement checkpointing to allow resuming from last saved state
- Save checkpoints at configurable intervals
- Provide mechanism to resume from checkpoint on subsequent runs
## Implementation Checklist
- [ ] Command-line interface compliant with specification
- [ ] Redis progress reporting implemented
- [ ] Signal handlers for SIGTERM and SIGINT
- [ ] Health check mode (`--check-health`)
- [ ] Resource monitoring (optional but recommended)
- [ ] Output JSON includes required base fields
- [ ] Error handling with graceful cleanup
- [ ] Performance overhead within 5% limit
- [ ] Documentation of processor-specific features
## Reference Implementation
The ASR processor (`scripts/asr_processor.py`) serves as the reference implementation for this contract, demonstrating all required and optional features.
## Changelog
### Version 1.0 (2025-03-27)
- Initial contract definition
- Based on ASR processor refactoring experience

253
docs_v1.0/PROCESSORS/SPECIFICATION/AI_PROCESSOR_COMPLIANCE_CHECKLIST.md Normal file
View File

@@ -0,0 +1,253 @@
---
document_type: "checklist"
service: "MOMENTRY_CORE"
title: "AI Processor Compliance Checklist"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "ai-processor"
- "compliance"
- "checklist"
- "quality-assurance"
ai_query_hints:
- "如何檢查 AI Processor 是否符合合約規範？"
- "各 Processor 的合規性狀態為何？"
- "AI Processor 合規檢查清單包含哪些項目？"
---
# AI Processor Compliance Checklist
## Overview
This checklist verifies compliance with the **AI-Driven Processor Contract v1.0**. All processors must pass all required checks to be considered contract-compliant.
## Compliance Status Summary
| Processor | Version | Contract | Compliance | Status | Last Verified |
|-----------|---------|----------|------------|--------|---------------|
| **ASR** | 2.1.0 | 1.0 | 100% | ✅ COMPLIANT | 2026-03-27 |
| **OCR** | 1.0.0 | 1.0 | 100% | ✅ COMPLIANT | 2026-03-27 |
| **YOLO** | 1.0.0 | 1.0 | 100% | ✅ COMPLIANT | 2026-03-27 |
| **Face** | 1.0.0 | 1.0 | 87.5% | ⚠️ PARTIAL | 2026-03-27 |
| **Pose** | 1.0.0 | 1.0 | 87.5% | ⚠️ PARTIAL | 2026-03-27 |
## Required Compliance Checks
### 1. Command-Line Interface ✅
**All processors PASS**
| Check | ASR | OCR | YOLO | Face | Pose |
|-------|-----|-----|------|------|------|
| `video_path` argument | ✅ | ✅ | ✅ | ✅ | ✅ |
| `output_path` argument | ✅ | ✅ | ✅ | ✅ | ✅ |
| `--uuid` or `-u` argument | ✅ | ✅ | ✅ | ✅ | ✅ |
| `--check-health` argument | ✅ | ✅ | ✅ | ✅ | ✅ |
| Hidden configuration args | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ |
**Notes**: All processors use environment variables for configuration (contract-compliant).
### 2. Health Check Mode ✅
**All processors PASS**
| Check | ASR | OCR | YOLO | Face | Pose |
|-------|-----|-----|------|------|------|
| Returns JSON output | ✅ | ✅ | ✅ | ✅ | ✅ |
| Includes `status` field | ✅ | ✅ | ✅ | ✅ | ✅ |
| Reports dependencies | ✅ | ✅ | ✅ | ✅ | ✅ |
| Includes timestamp | ⚠️ | ⚠️ | ✅ | ✅ | ✅ |
| Exit code 0 for healthy | ✅ | ✅ | ✅ | ✅ | ✅ |
**Notes**: ASR and OCR missing timestamp in health check (minor issue).
### 3. Signal Handling ✅
**All processors PASS**
| Check | ASR | OCR | YOLO | Face | Pose |
|-------|-----|-----|------|------|------|
| `signal` module imported | ✅ | ✅ | ✅ | ✅ | ✅ |
| SIGTERM handler | ✅ | ✅ | ✅ | ✅ | ✅ |
| SIGINT handler | ✅ | ✅ | ✅ | ✅ | ✅ |
| Graceful shutdown patterns | ✅ | ✅ | ✅ | ✅ | ✅ |
### 4. Redis Progress Reporting ✅
**All processors PASS** (Redis is optional)
| Check | ASR | OCR | YOLO | Face | Pose |
|-------|-----|-----|------|------|------|
| RedisPublisher import | ✅ | ✅ | ✅ | ✅ | ✅ |
| Progress reporting | ✅ | ✅ | ✅ | ✅ | ✅ |
| Message types | ✅ | ✅ | ✅ | ✅ | ✅ |
### 5. JSON Output Structure ⚠️
**ASR, OCR, YOLO PASS | Face, Pose FAIL**
| Check | ASR | OCR | YOLO | Face | Pose |
|-------|-----|-----|------|------|------|
| `processor_name` field | ✅ | ✅ | ✅ | ❌ | ❌ |
| `processor_version` field | ✅ | ✅ | ✅ | ✅ | ✅ |
| `contract_version` field | ✅ | ✅ | ✅ | ✅ | ✅ |
| JSON output patterns | ✅ | ✅ | ✅ | ✅ | ✅ |
**Critical Issues**: Face and Pose processors missing `processor_name` field in JSON output.
### 6. Error Handling ✅
**All processors PASS**
| Check | ASR | OCR | YOLO | Face | Pose |
|-------|-----|-----|------|------|------|
| Exception handling | ✅ | ✅ | ✅ | ✅ | ✅ |
| Graceful cleanup | ✅ | ✅ | ✅ | ✅ | ✅ |
| Exit codes | ✅ | ✅ | ✅ | ✅ | ✅ |
### 7. Unified Configuration ✅
**All processors PASS**
| Check | ASR | OCR | YOLO | Face | Pose |
|-------|-----|-----|------|------|------|
| `MOMENTRY_` env vars | ✅ | ✅ | ✅ | ✅ | ✅ |
| Timeout handling | ✅ | ✅ | ✅ | ✅ | ✅ |
## Critical Issues to Address
### 1. Face Processor - JSON Output Structure
- **Issue**: Missing `processor_name` field in JSON output
- **Impact**: Non-compliant with contract requirement
- **Priority**: HIGH
- **Fix**: Add `"processor_name": "face"` to all JSON return statements
### 2. Pose Processor - JSON Output Structure
- **Issue**: Missing `processor_name` field in JSON output
- **Impact**: Non-compliant with contract requirement
- **Priority**: HIGH
- **Fix**: Add `"processor_name": "pose"` to all JSON return statements
### 3. ASR/OCR Processors - Health Check Timestamp
- **Issue**: Missing timestamp in health check output
- **Impact**: Minor compliance issue
- **Priority**: LOW
- **Fix**: Add `"timestamp": datetime.now().isoformat()` to health check
## Performance Compliance
**Note**: Performance benchmarks (<5% overhead) have not been run yet. This is a separate verification step.
| Processor | Baseline Tested | Overhead Verified | Status |
|-----------|----------------|-------------------|--------|
| ASR | ❌ | ❌ | PENDING |
| OCR | ❌ | ❌ | PENDING |
| YOLO | ❌ | ❌ | PENDING |
| Face | ❌ | ❌ | PENDING |
| Pose | ❌ | ❌ | PENDING |
## Implementation Quality Assessment
### High Quality Implementations (95-100% compliance)
1. **ASR Processor v2.1.0** - Reference implementation
- Lines reduced from 953 to 341 (64% reduction)
- Comprehensive timeout handling
- Model caching for performance
- Excellent error handling
2. **OCR Processor v1.0.0** - Well-structured
- EasyOCR integration with caching
- Good frame processing logic
- Clear configuration structure
3. **YOLO Processor v1.0.0** - Feature-rich
- Resume support with checkpoints
- Auto-save functionality
- COCO class filtering
### Needs Improvement (80-90% compliance)
1. **Face Processor v1.0.0** - Incomplete implementation
- File appears truncated (257 vs expected 621 lines)
- Missing JSON structure fields
- Needs complete rewrite
2. **Pose Processor v1.0.0** - Incomplete implementation
- File appears truncated (291 vs expected 666 lines)
- Missing JSON structure fields
- Needs complete rewrite
## Verification Tools
### Automated Verification
```bash
# Verify all processors
python3 verify_processor_compliance.py
# Verify specific processor
python3 verify_processor_compliance.py --processor asr
# Generate report
python3 verify_processor_compliance.py --output report.md
```
### Manual Verification Steps
1. **CLI Test**: `python3 script.py --help`
2. **Health Check**: `python3 script.py dummy.mp4 dummy.json --check-health`
3. **Signal Test**: Run processor and send SIGINT (Ctrl+C)
4. **Output Test**: Process sample video and verify JSON structure
## Remediation Plan
### Phase 1: Critical Fixes (Immediate)
1. **Fix Face processor JSON output** - Add missing `processor_name` field
2. **Fix Pose processor JSON output** - Add missing `processor_name` field
3. **Complete Face processor implementation** - Rewrite from template
4. **Complete Pose processor implementation** - Rewrite from template
### Phase 2: Minor Improvements (Next 7 days)
1. Add timestamps to ASR/OCR health checks
2. Run performance benchmarks for all processors
3. Update documentation with compliance status
4. Integrate with monitoring system
### Phase 3: Remaining Processors (Next 14 days)
1. **ASRX Processor** - Standardize to contract
2. **Caption Processor** - Standardize to contract
3. **CUT Processor** - Standardize to contract
4. **Story Processor** - Standardize to contract
## Success Criteria
### Contract Compliance
- [x] 3/5 processors at 100% compliance (ASR, OCR, YOLO)
- [ ] 5/5 processors at 100% compliance (Face, Pose pending)
- [ ] All processors pass performance benchmarks (<5% overhead)
### Documentation
- [x] AI-Driven Processor Contract defined
- [x] Processor Standardization Template created
- [x] Revision Records documented
- [x] Compliance Checklist created
- [ ] User guides updated
### Integration
- [x] Unified configuration in Rust
- [ ] Monitoring integration complete
- [ ] Performance dashboards operational
## Next Steps
1. **Immediate**: Fix Face and Pose processor JSON output structure
2. **Short-term**: Complete Face and Pose processor implementations
3. **Medium-term**: Standardize remaining processors (ASRX, Caption, CUT, Story)
4. **Long-term**: Performance benchmarking and optimization
## References
1. [AI-Driven Processor Contract](../REFERENCE/AI_DRIVEN_PROCESSOR_CONTRACT.md)
2. [Processor Standardization Template](../REFERENCE/PROCESSOR_STANDARDIZATION_TEMPLATE.md)
3. [AI Processor Module Revision Records](../REFERENCE/AI_PROCESSOR_MODULE_REVISION_RECORDS.md)
4. [ASR Configuration Unification](../REFERENCE/ASR_CONFIGURATION_UNIFICATION.md)
## Changelog
### Version 1.0 (2026-03-27)
- Initial compliance checklist created
- 3/5 processors at 100% compliance
- Automated verification tool created
- Comprehensive documentation structure established

242
docs_v1.0/PROCESSORS/SPECIFICATION/PROCESSOR_OUTPUT_SPEC.md Normal file
View File

@@ -0,0 +1,242 @@
---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "Momentry Core 處理器產出規範 (Pre-Chunk & Frame) (v1.0)"
date: "2026-04-21"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "momentry"
- "core"
- "處理器產出規範"
ai_query_hints:
- "查詢 Momentry Core 處理器產出規範 (Pre-Chunk & Frame) (v1.0) 的內容"
- "Momentry Core 處理器產出規範 (Pre-Chunk & Frame) (v1.0) 的主要目的是什麼？"
- "如何操作或實施 Momentry Core 處理器產出規範 (Pre-Chunk & Frame) (v1.0)？"
---
# Momentry Core 處理器產出規範 (Pre-Chunk & Frame) (v1.0)
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-21 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-21 | 定義處理器產出 JSON 之 Pre-chunk 與 Frame 結構標準 | OpenCode | OpenCode / Qwen3.6-Plus |
---
## 0. 設計原則
為確保所有處理器（ASR, OCR, Face, YOLO, Cut）產出的時間軸精確且一致，本規範定義以下核心原則：
1. **幀為本位 (Frame-Based)**：
* 所有時間計算的**唯一權威來源**是幀編號 (`frame_number`)。
* 開始時間、結束時間、長度皆以幀為單位 (`start_frame`, `end_frame`, `length_frames`)。
2. **秒數為參考 (Timestamp is Derived)**：
* 秒數 (`timestamp_sec`, `start_time_sec`) 僅供人類閱讀與外部 API 參考。
* 計算公式：`time = frame / fps`。
* FPS 資訊必須與 `ffprobe` 探針結果嚴格一致。
3. **結構統一**：
* 產出分為兩大層級：**Frame (單幀檢測)** 與 **Pre-Chunk (時間區間聚合)**。
---
## 1. 核心資料結構
### 1.1 Frame (幀級資料)
適用於需要逐幀記錄空間座標或逐幀屬性的任務 (如 OCR, Face, YOLO)。
```json
{
"frame_number": 12345,
"timestamp_sec": 411.91,
"fps": 29.97,
"processor": "face_detection",
"data": {
"faces": [
{
"box": { "x": 100, "y": 50, "w": 60, "h": 60 },
"identity": null,
"confidence": 0.98
}
]
}
}
```
| 欄位 | 類型 | 說明 | 計算方式 |
|:---|:---|:---|:---|
| `frame_number` | `int` | **主鍵**，物理幀編號 | 從 0 開始計數 |
| `timestamp_sec` | `float` | 時間戳記 (秒) | `frame_number / fps` |
| `fps` | `float` | 幀率 | 來自 `ffprobe` 探針結果 |
| `data` | `object` | 偵測結果負載 | 依處理器類型定義 |
### 1.2 Pre-Chunk (預切片資料)
適用於具有持續時間的語意片段 (如 ASR 語句、鏡頭切換、OCR 持續文字)。
```json
{
"pre_chunk_id": "pc_001",
"type": "asr_segment",
"start_frame": 1200,
"end_frame": 1500,
"duration_frames": 300,
"start_time_sec": 40.04,
"end_time_sec": 50.05,
"fps": 29.97,
"data": {
"text": "這是一個非常長的句子...",
"speaker": "SPEAKER_00"
}
}
```
| 欄位 | 類型 | 說明 | 計算方式 |
|:---|:---|:---|:---|
| `start_frame` | `int` | **起始幀** | - |
| `end_frame` | `int` | **結束幀** | - |
| `duration_frames` | `int` | 持續幀數 | `end_frame - start_frame + 1` |
| `start_time_sec` | `float` | 起始秒數 | `start_frame / fps` |
| `end_time_sec` | `float` | 結束秒數 | `end_frame / fps` |
| `data` | `object` | 內容負載 | 依處理器類型定義 |
---
## 2. 處理器產出規範 (JSON Spec)
### 2.1 ASR (語音識別) -> Pre-Chunk
ASR 產出主要是文字片段，因此歸類為 `Pre-Chunk`。
* **輸出檔名**: `{uuid}_asr.json`
* **結構**: Array of Pre-Chunk
```json
[
{
"start_frame": 0,
"end_frame": 149,
"start_time_sec": 0.0,
"end_time_sec": 5.0,
"data": {
"text": "Hello world, this is a test.",
"speaker": "SPEAKER_00",
"language": "en"
}
},
...
]
```
### 2.2 Face (人臉偵測) -> Frame
人臉位置可能每幀微動，因此以 `Frame` 記錄最精確。
* **輸出檔名**: `{uuid}_faces.json`
* **結構**: Object containing Array of Frames
```json
{
"info": {
"fps": 29.97,
"total_frames": 5000
},
"frames": [
{
"frame_number": 10,
"timestamp_sec": 0.33,
"data": {
"faces": [
{ "box": { "x": 10, "y": 10, "w": 50, "h": 50 }, "confidence": 0.99 }
]
}
}
]
}
```
### 2.3 OCR (文字辨識) -> Frame
通常以抽樣 (Sample) 方式進行 (如每 30 幀抽 1 幀)。
* **輸出檔名**: `{uuid}_ocr.json`
* **結構**: Array of Frames
```json
[
{
"frame_number": 1200,
"timestamp_sec": 40.04,
"data": {
"texts": [
{ "text": "CAST", "bbox": [100, 100, 200, 50] },
{ "text": "Cary Grant", "bbox": [100, 150, 200, 30] }
]
}
}
]
```
### 2.4 Cut (鏡頭切割) -> Pre-Chunk
鏡頭切割定義了場景的邊界，是典型的 Pre-Chunk。
* **輸出檔名**: `{uuid}_cuts.json`
* **結構**: Array of Pre-Chunk
```json
[
{
"start_frame": 0,
"end_frame": 299,
"start_time_sec": 0.0,
"end_time_sec": 10.0,
"data": {
"scene_type": "indoor",
"cut_score": 0.95
}
}
]
```
---
## 3. 數據一致性檢查
為確保產出符合規範，寫入資料庫前需執行以下檢查：
1. **FPS 校驗**: JSON 中的 `fps` 必須等於 `assets` 表中 `media_info->fps` 的值。誤差允許範圍 `±0.01`。
2. **幀邊界**: `start_frame` 必須 `>= 0`，`end_frame` 必須 `<= total_frames`。
3. **時間換算驗證**:
* `abs(timestamp_sec - (frame_number / fps)) < 0.001`
---
## 4. 與 Chunk 系統的關聯
Processor 產出的是 **Raw Data (Pre-chunk / Frames)**。
後續的 **Chunk Strategy (Rule 1/2/3)** 會讀取這些 Raw Data 並進行聚合，生成最終的 `chunks` 表記錄。
* **Input**: 多個 Pre-chunks / Frames
* **Process**: 合併 (Merge)、摘要 (Summarize)、嵌入 (Embedding)
* **Output**: `chunks` 表 (具備語意向量)
```mermaid
graph LR
A[ASR Pre-Chunk] --> C(Chunk Aggregator)
B[OCR Frame] --> C
D[Cut Pre-Chunk] --> C
C --> E[Final Chunk with Vector]
```
此設計確保了**原始物理資訊 (幀)** 的完整保留，同時允許上層邏輯進行靈活的語意組裝。

493
docs_v1.0/PROCESSORS/SPECIFICATION/PROCESSOR_STANDARDIZATION_TEMPLATE.md Normal file
View File

@@ -0,0 +1,493 @@
---
document_type: "reference_doc"
service: "MOMENTRY_CORE"
title: "Processor Standardization Template"
date: "2026-04-25"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "processor"
- "template"
- "standardization"
ai_query_hints:
- "查詢 Processor Standardization Template 的內容"
- "Processor Standardization Template 的主要目的是什麼？"
- "如何操作或實施 Processor Standardization Template？"
---
# Processor Standardization Template
## Overview
This template provides a standardized approach for creating contract-compliant processor modules based on the AI-Driven Processor Contract. Use this template when creating new processors or updating existing ones.
## Template Structure
### 1. Python Processor Script Template
```python
#!/opt/homebrew/bin/python3.11
"""
{PROCESSOR_NAME} Processor - AI-Driven Processor Contract Version {VERSION}
Compliant with AI-Driven Processor Contract v1.0
Effective Date: {DATE}
Features:
1. Standardized command-line interface
2. Redis progress reporting
3. Signal handling (SIGTERM, SIGINT)
4. Health check mode
5. Resource monitoring
6. Contract-compliant JSON output
7. Unified configuration
"""
import sys
import json
import os
import argparse
import signal
import tempfile
import time
import subprocess
import traceback
import threading
from datetime import datetime
from pathlib import Path
from typing import Dict, Any, List, Optional, Tuple
import atexit
# Redis Publisher for progress reporting
try:
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from redis_publisher import RedisPublisher
REDIS_AVAILABLE = True
except ImportError:
REDIS_AVAILABLE = False
print(
f"WARNING: RedisPublisher not available, progress reporting disabled",
file=sys.stderr,
)
# Contract version
CONTRACT_VERSION = "1.0"
PROCESSOR_NAME = "{processor_name}" # e.g., "ocr", "yolo", "face", "pose"
PROCESSOR_VERSION = "{version}" # e.g., "1.0.0"
# Unified configuration defaults
DEFAULT_TIMEOUT = 3600 # 1 hour
# Add processor-specific defaults here
# Signal handling with timeout support
class SignalHandler:
"""Handle system signals for graceful shutdown"""
# ... (same as ASR template)
# Timeout manager
class TimeoutManager:
"""Manage processing timeouts"""
# ... (same as ASR template)
# Health check functions
def check_environment() -> Dict[str, Any]:
"""Check environment and dependencies"""
checks = []
# Check 1: Processor-specific dependencies
try:
# Import processor-specific libraries
# e.g., import cv2, import pytesseract, etc.
checks.append({
"name": "{dependency_name}",
"status": "available",
"version": "x.x.x" # Get actual version
})
except ImportError:
checks.append({"name": "{dependency_name}", "status": "missing", "version": None})
# Check 2: FFmpeg/FFprobe (if needed)
# ... (same as ASR template)
# Check 3: Redis (optional)
# ... (same as ASR template)
# Check 4: Python version
# ... (same as ASR template)
return {"status": "healthy", "dependencies": checks}
# Main processor class
class {ProcessorClass}Processor:
"""{PROCESSOR_NAME} Processor compliant with AI-Driven Processor Contract"""
def __init__(
self,
video_path: str,
output_path: str,
uuid: Optional[str] = None,
check_health: bool = False,
):
self.video_path = video_path
self.output_path = output_path
self.uuid = uuid or ""
self.check_health = check_health
# Get unified configuration from environment
self.timeout = int(os.environ.get(f"MOMENTRY_{PROCESSOR_NAME.upper()}_TIMEOUT", str(DEFAULT_TIMEOUT)))
# Add processor-specific configuration here
# Initialize components
self.publisher = None
if REDIS_AVAILABLE and self.uuid:
try:
self.publisher = RedisPublisher(self.uuid)
except Exception as e:
print(f"[{PROCESSOR_NAME}] Failed to initialize Redis publisher: {e}", file=sys.stderr)
self.timeout_manager = TimeoutManager(self.timeout, self.timeout, self.timeout)
self.signal_handler = SignalHandler()
self.start_time = time.time()
self.cleanup_files = []
# Set up signal handling
self.signal_handler.setup()
atexit.register(self.cleanup)
def publish(self, msg_type: str, message: str, progress: Optional[float] = None):
"""Publish message to Redis if available"""
# ... (same as ASR template)
def validate_input(self) -> Tuple[bool, str]:
"""Validate input file"""
if not os.path.exists(self.video_path):
return False, f"Video file not found: {self.video_path}"
# Add processor-specific validation
# e.g., check video format, resolution, etc.
return True, "Input validation passed"
def process(self) -> Dict[str, Any]:
"""Main processing method"""
self.publish("info", f"Starting {PROCESSOR_NAME} processing: {self.video_path}")
# Validate input
is_valid, validation_msg = self.validate_input()
if not is_valid:
raise RuntimeError(f"Input validation failed: {validation_msg}")
self.publish("info", "Input validation passed")
# Start timeout monitoring
self.timeout_manager.start_overall_timer()
# Processor-specific processing logic
# This is where the actual processing happens
try:
result = self._process_core()
except Exception as e:
raise RuntimeError(f"Processing failed: {e}")
# Check for timeout
timeout_reached, timeout_msg = self.timeout_manager.check_timeout("processing")
if timeout_reached:
raise RuntimeError(f"Processing {timeout_msg}")
# Prepare final result
final_result = {
"processor_name": PROCESSOR_NAME,
"processor_version": PROCESSOR_VERSION,
"contract_version": CONTRACT_VERSION,
"video_path": self.video_path,
"timestamp": datetime.utcnow().isoformat() + "Z",
"processing_time_seconds": time.time() - self.start_time,
"configuration": {
"timeout_seconds": self.timeout,
# Add processor-specific configuration
},
**result, # Include processor-specific results
}
self.publish("progress", f"{PROCESSOR_NAME} processing complete", 1.0)
self.publish("complete", f"{PROCESSOR_NAME} processing completed successfully in {final_result['processing_time_seconds']:.1f}s")
return final_result
def _process_core(self) -> Dict[str, Any]:
"""Core processing logic - implement in subclass"""
raise NotImplementedError("Subclasses must implement _process_core")
def cleanup(self):
"""Clean up temporary resources"""
# ... (same as ASR template)
def main():
"""Main entry point"""
parser = argparse.ArgumentParser(
description=f"{PROCESSOR_NAME} Processor - AI-Driven Processor Contract Version {PROCESSOR_VERSION}"
)
# Required arguments
parser.add_argument("video_path", help="Path to input video file")
parser.add_argument("output_path", help="Path where JSON output should be written")
# Optional arguments
parser.add_argument("--uuid", "-u", default="", help="UUID for Redis progress reporting")
parser.add_argument("--check-health", action="store_true", help="Perform health check and exit")
# Hidden configuration arguments (following contract)
parser.add_argument("--timeout", type=int, help=argparse.SUPPRESS)
# Add processor-specific hidden arguments
args = parser.parse_args()
# Health check mode
if args.check_health:
health_result = check_environment()
print(json.dumps(health_result, indent=2))
sys.exit(0 if health_result["status"] == "healthy" else 1)
# Create processor
processor = {ProcessorClass}Processor(
video_path=args.video_path,
output_path=args.output_path,
uuid=args.uuid if args.uuid else None,
check_health=args.check_health,
)
try:
# Process video
result = processor.process()
# Write output
with open(args.output_path, "w", encoding="utf-8") as f:
json.dump(result, f, indent=2, ensure_ascii=False)
print(f"[{PROCESSOR_NAME}] Processing completed successfully")
print(f"[{PROCESSOR_NAME}] Output written to: {args.output_path}")
sys.exit(0)
except RuntimeError as e:
error_msg = f"{PROCESSOR_NAME} processing failed: {e}"
processor.publish("error", error_msg)
print(f"[{PROCESSOR_NAME}] ERROR: {error_msg}", file=sys.stderr)
sys.exit(1)
except KeyboardInterrupt:
processor.publish("warning", "Processing interrupted by user")
print(f"[{PROCESSOR_NAME}] Processing interrupted by user", file=sys.stderr)
sys.exit(130) # Standard exit code for SIGINT
except Exception as e:
error_msg = f"Unexpected error: {e}\n{traceback.format_exc()}"
processor.publish("error", error_msg)
print(f"[{PROCESSOR_NAME}] CRITICAL ERROR: {error_msg}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
```
### 2. Rust Configuration Template
```rust
// Add to src/core/config.rs
pub mod {processor_name} { // e.g., ocr, yolo, face, pose
use super::*;
// Unified configuration
pub static TIMEOUT_SECS: Lazy<u64> = Lazy::new(|| {
env::var(format!("MOMENTRY_{}_TIMEOUT", {PROCESSOR_NAME_UPPER}))
.unwrap_or_else(|_| "3600".to_string())
.parse()
.unwrap_or(3600)
});
// Add processor-specific configuration
// e.g., model paths, confidence thresholds, etc.
}
```
### 3. Rust Processor Module Template
```rust
use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};
use std::time::Duration;
use super::executor::PythonExecutor;
use crate::core::config::{processor, {processor_name}};
#[derive(Debug, Serialize, Deserialize)]
pub struct {ProcessorClass}Result {
// Define processor-specific result structure
}
pub async fn process_{processor_name}(
video_path: &str,
output_path: &str,
uuid: Option<&str>,
) -> Result<{ProcessorClass}Result> {
let executor = PythonExecutor::new()?;
let script_path = executor.script_path("{processor_name}_processor_contract.py");
tracing::info!("[{PROCESSOR_NAME_UPPER}] Starting processing: {}", video_path);
executor
.run(
"{processor_name}_processor_contract.py",
&[video_path, output_path],
uuid,
"{PROCESSOR_NAME_UPPER}",
Some(Duration::from_secs(*{processor_name}::TIMEOUT_SECS)),
)
.await
.with_context(|| format!("Failed to run {:?}", script_path))?;
let json_str = std::fs::read_to_string(output_path)
.context("Failed to read {PROCESSOR_NAME} output")?;
let result: {ProcessorClass}Result =
serde_json::from_str(&json_str).context("Failed to parse {PROCESSOR_NAME} output")?;
tracing::info!("[{PROCESSOR_NAME_UPPER}] Processing completed successfully");
Ok(result)
}
```
## Implementation Steps
### Step 1: Analyze Existing Processor
1. Review current Python script (`scripts/{processor_name}_processor.py`)
2. Identify dependencies and requirements
3. Understand input/output formats
4. Note any configuration needs
### Step 2: Create Contract-Compliant Version
1. Copy template to `scripts/{processor_name}_processor_contract.py`
2. Fill in processor-specific details:
- `PROCESSOR_NAME` and `PROCESSOR_VERSION`
- Dependencies in `check_environment()`
- Configuration defaults
- Core processing logic in `_process_core()`
- Result structure
### Step 3: Update Rust Configuration
1. Add configuration module to `src/core/config.rs`
2. Define environment variables and defaults
### Step 4: Update Rust Processor Module
1. Update or create `src/core/processor/{processor_name}.rs`
2. Use contract-compliant script
3. Pass configuration via environment variables
### Step 5: Test and Validate
1. Create test script
2. Verify health check mode
3. Test basic processing
4. Validate contract compliance
5. Test configuration unification
## Processor-Specific Considerations
### OCR Processor
- **Dependencies**: Tesseract, OpenCV, PIL
- **Configuration**: Language models, confidence thresholds
- **Output**: Text with bounding boxes, confidence scores
### YOLO Processor
- **Dependencies**: Ultralytics YOLO, OpenCV
- **Configuration**: Model path, confidence threshold, classes
- **Output**: Detected objects with bounding boxes, classes, confidence
### Face Processor
- **Dependencies**: face_recognition, dlib, OpenCV
- **Configuration**: Model paths, encoding methods
- **Output**: Face locations, encodings, landmarks
### Pose Processor
- **Dependencies**: MediaPipe, OpenCV
- **Configuration**: Model complexity, confidence thresholds
- **Output**: Pose keypoints, connections, confidence scores
## Configuration Variables
Each processor should support:
- `MOMENTRY_{PROCESSOR}_TIMEOUT` - Overall timeout
- `MOMENTRY_{PROCESSOR}_MODEL_PATH` - Model file path (if applicable)
- `MOMENTRY_{PROCESSOR}_CONFIDENCE` - Confidence threshold (if applicable)
- Processor-specific configuration
## Testing Checklist
- [ ] Health check mode works
- [ ] Basic processing with sample video
- [ ] Configuration loading from environment
- [ ] Signal handling (SIGINT, SIGTERM)
- [ ] Timeout handling
- [ ] Redis progress reporting (if Redis available)
- [ ] Output JSON follows contract schema
- [ ] Error handling and graceful degradation
## Migration Strategy
1. **Phase 1**: Create contract-compliant version alongside existing
2. **Phase 2**: Update Rust module to use new version
3. **Phase 3**: Test thoroughly
4. **Phase 4**: Remove old version (keep as backup)
## Example: OCR Processor Implementation
### Configuration (config.rs)
```rust
pub mod ocr {
use super::*;
pub static TIMEOUT_SECS: Lazy<u64> = Lazy::new(|| {
env::var("MOMENTRY_OCR_TIMEOUT")
.unwrap_or_else(|_| "1800".to_string())
.parse()
.unwrap_or(1800)
});
pub static LANGUAGE: Lazy<String> = Lazy::new(|| {
env::var("MOMENTRY_OCR_LANGUAGE")
.unwrap_or_else(|_| "eng".to_string())
});
pub static CONFIDENCE_THRESHOLD: Lazy<f32> = Lazy::new(|| {
env::var("MOMENTRY_OCR_CONFIDENCE")
.unwrap_or_else(|_| "0.7".to_string())
.parse()
.unwrap_or(0.7)
});
}
```
### Python Script
- `PROCESSOR_NAME = "ocr"`
- `PROCESSOR_VERSION = "1.0.0"`
- Dependencies: `pytesseract`, `opencv-python`, `PIL`
- Core logic: Extract frames, run OCR, return text with positions
## Success Criteria
1. **Contract Compliance**: Follows AI-Driven Processor Contract
2. **Configuration Unification**: Uses unified configuration system
3. **Backward Compatibility**: Existing workflows continue to work
4. **Improved Maintainability**: Clean, standardized code
5. **Better Observability**: Consistent logging and monitoring
---
*Template Version: 1.0*
*Last Updated: 2026-03-27*
*Based on: AI-Driven Processor Contract v1.0*