# AGENTS.md - 2026 AI Video Upscaler Agent Directives

Tài liệu chỉ thị và quy chuẩn kỹ thuật dành riêng cho các AI Agent (Antigravity Host Agent, Subagents, Worker Agents) khi sử dụng hoặc bảo trì công cụ Super-Resolution trong toàn bộ hệ sinh thái dự án.

---

## 1. NGUYÊN TẮC CỐT LÕI (CORE INVARIANTS)

1. **Zero-Local VRAM Invariant**:
   - Tuyệt đối KHÔNG chạy model upscale nặng trên máy local (GTX 1660 Super).
   - Mọi tiến trình Super-Resolution phải được ủy thác lên Cloud qua **Hugging Face Pro ZeroGPU ($0.00)** hoặc **RunPod On-Demand**.
2. **Deterministic Fallback**:
   - Mặc định luôn sử dụng `--engine auto`.
   - Nếu Hugging Face ZeroGPU trả về lỗi (hết quota, timeout, queue full), engine tự động chuyển sang RunPod mà không dừng tiến trình hay hỏi lại người dùng.
3. **Pristine Audio & Aspect Ratio Preservation**:
   - Giữ nguyên vẹn 100% luồng âm thanh gốc (AAC/PCM stereo).
   - Tự động nhận diện video ngang 16:9 ($3840 \times 2160$) và video dọc 9:16 Shorts ($2160 \times 3840$).
4. **Action-Driven Verification (Zero Lip-Service)**:
   - Nghiêm cấm Agent báo cáo hoàn thành khi chưa dùng `ffprobe` kiểm chứng độ phân giải file xuất thực tế.

---

## 2. GIAO DIỆN THỰC THI (AGENT APIS)

### Cách 1: Gọi CLI qua `run_command` (Khuyên dùng)
```powershell
# Chạy mặc định (Tự động ưu tiên HF ZeroGPU $0 + RunPod dự phòng):
c:\Projects\video-upscaler\upscale.bat --input "path/to/input.mp4" --output "path/to/output_4k.mp4"

# Chạy test nhanh 5s để nghiệm thu trước khi render toàn bộ:
c:\Projects\video-upscaler\upscale.bat --input "path/to/input.mp4" --output "path/to/test_4k.mp4" --duration 5.0

# Ép chạy GPU quái vật RunPod (RTX 5090 / 4090):
c:\Projects\video-upscaler\upscale.bat --input "path/to/input.mp4" --output "path/to/output_4k.mp4" --engine runpod --gpu_type 5090
```

### Cách 2: Import Trực Tiếp Bằng Python Từ Project Khác
```python
import sys

# Thêm đường dẫn công cụ dùng chung
UPSCALER_ROOT = r"c:\Projects\video-upscaler"
if UPSCALER_ROOT not in sys.path:
    sys.path.append(UPSCALER_ROOT)

from purescale_engine import upscale_video

# Thực thi hàm
upscale_video(
    input_video="path/to/source.mp4",
    output_video="path/to/output_4k.mp4",
    engine="auto",        # "auto" | "hf" | "runpod"
    model_type="photo",   # "photo" (người thật/lịch sử) | "anime" (2D animation)
    gpu_type="4090",      # 5090, 4090, 3090 khi chạy RunPod
    start_sec=0.0,
    duration=None
)
```

---

## 3. CHECKLIST NGHIỆM THU DÀNH CHO AGENT

Sau khi chạy xong lệnh upscale, Agent BẮT BUỘC thực hiện kiểm tra:

```powershell
# 1. Kiểm tra file đích tồn tại:
Test-Path "path/to/output_4k.mp4"

# 2. Kiểm tra độ phân giải thực tế bằng ffprobe:
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,r_frame_rate,duration -of json "path/to/output_4k.mp4"
```

Tiêu chí đạt:
- `width` hoặc `height` đạt mốc `3840`.
- Thời lượng video khớp với bản gốc.
- Không có lỗi stream hỏng.

---

## 4. TÍCH HỢP LIÊN DỰ ÁN

- **Skill toàn cục**: Đã đóng gói tại `C:\Users\Admin\.gemini\config\skills\video-4k-upscaler\SKILL.md`.
- **Triggers**: `'upscale video', 'nâng cấp 4k', 'video 4k', 'upscale 4k', 'tăng chất lượng video', 'super resolution video'`.
- Mọi dự án (`Historical`, `Tran_Empire`, `KieuStory`, v.v.) chỉ cần gọi tool này mà không cần sao chép code hay cài đặt lại thư viện.