🤖 AGENT HANDOVER PROTOCOL (Dành cho AI Agent)

QUAN TRỌNG: Nếu bạn là AI Agent mới, hãy đọc file này kết hợp với doc/00.AGENT_ARCHITECTURE_MAP.md trước khi viết bất kỳ dòng code nào.

1. Tóm tắt "Bộ nhớ" Dự án (Memory Snapshot)

Dự án này là một hệ thống Enterprise RAG (Retrieval-Augmented Generation) với các đặc điểm kỹ thuật:

Distributed VLM OCR: Dùng máy chủ LAN (10.202.50.3:8080) chạy Vintern-3B để trích xuất Markdown từ PDF.
Modular Provider Pattern: Tách biệt Storage (SharePoint) và LLM (Gemini, Groq, Local).
Semantic Indexing: Dùng vietnamese-sbert (local) tạo vector 768 chiều, lưu vào OpenSearch k-NN HNSW.
FastAPI Backend: API tại port 8000. Endpoint: /health, /chat.
Glassmorphism UI: Giao diện web tại frontend/, gọi http://localhost:8000/chat.

Pipeline hiện tại (ĐÃ HOẠT ĐỘNG):

SharePoint → Ingestion → VLM OCR → Chunking → OpenSearch → Search → RAG Chat → FastAPI → Frontend

2. Trạng thái triển khai

✅ Đã hoàn thành

Module	File	Mô tả
Ingestion	`ingestion/providers/sharepoint_provider.py`	Delta Query + Pagination + get_item_details
Sync Engine	`ingestion/sync.py`	Provider-agnostic, nhận BaseStorageProvider
DCE	`extraction/dce.py`	Document Classification Engine (phân loại file)
PDF Inspector	`extraction/pdf_inspector.py`	TEXT_PDF / SCAN_PDF / DRAWING_PDF / AMBIGUOUS_PDF
Magic Numbers	`extraction/magic_numbers.py`	Header byte validation
OCR	`extraction/ocr_service.py`	VLM Client (Vintern-3B qua LAN)
Chunking	`chunking/markdown_chunker.py`	Semantic Markdown rules + page tracking
Indexing	`indexing/vector_store.py`	OpenSearch k-NN + delete_by_file_id dedup
Search	`search/retriever.py`	Semantic k-NN vector search
RAG Chat	`chat/rag_engine.py`	Search → Context → LLM
LLM Factory	`chat/llm_factory.py`	Gemini / Groq / Local
API	`api/main.py`	FastAPI port 8000
Frontend	`frontend/`	Glassmorphism UI (HTML/CSS/JS)
Bug fixes	Nhiều file	SharePoint links (Bug #101), Chunk dedup

❌ Chưa triển khai (Phase 8)

DOCX Text Extraction: Trích xuất text từ DOCX không cần OCR
XLSX Text Extraction: Trích xuất header + key columns từ Excel
Permission Enforcement: ACL filtering theo user/group
Authentication UI: OAuth2 login
Ingestion API: Trigger sync từ frontend
Logging & Audit: Structured logging

3. Hướng dẫn dành cho AI Agent tiếp theo

Luôn kiểm tra .env: Toàn bộ cấu hình nằm ở đây. Không bao giờ hardcode.
Sử dụng core/config.py: Cửa ngõ duy nhất để truy cập cài đặt.
UTF-8: Mọi I/O phải có encoding='utf-8'. Đặt export PYTHONIOENCODING=utf-8.
Cập nhật tài liệu: Khi hoàn thành Phase hoặc thay đổi kiến trúc, BẮT BUỘC cập nhật file này và 00.AGENT_ARCHITECTURE_MAP.md.
Đọc doc/14.Project-Bridge-Context-for-New-Chat.md: Đây là "hợp đồng kiến trúc" - không thay đổi các quyết định đã chốt.

4. Cách cập nhật Tài liệu (Protocol for Updates)

Bước 1: Cập nhật trạng thái trong doc/00.AGENT_ARCHITECTURE_MAP.md (đánh dấu ✅ vào checkbox).
Bước 2: Nếu phát hiện lỗi mới, ghi lại vào mục "Lịch sử các lỗi khét tiếng" kèm giải pháp.
Bước 3: Cập nhật mục Trạng thái triển khai trong file này.

5. Lệnh chạy nhanh (Quick Start)

# Khởi động OpenSearch
docker-compose up -d opensearch

# Chạy Backend (FastAPI port 8000)
python3 api/main.py

# Mở Frontend
# Mở frontend/index.html trong trình duyệt (hoặc dùng Live Server)

# Nạp dữ liệu từ SharePoint → OCR → Chunk → Index
python3 test_rag_pipeline.py

6. Kiểm tra nhanh (Verification)

# 1. Kiểm tra cú pháp Python
python3 -m py_compile ingestion/graph_client.py
python3 -m py_compile ingestion/providers/sharepoint_provider.py
python3 -m py_compile ingestion/sync.py
python3 -m py_compile indexing/vector_store.py
python3 -m py_compile api/main.py
python3 -m py_compile test_rag_pipeline.py

# 2. Test kết nối Graph API
python3 test_graph_smoke.py

# 3. Test toàn bộ pipeline (cần OpenSearch + VLM server)
python3 test_rag_pipeline.py

# 4. Kiểm tra metadata
cat ingestion_output.json | python3 -m json.tool | grep -E '"web_url"|"download_url"'

# 5. Test API endpoint
curl http://localhost:8000/health
curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" -d '{"query":"test"}'

Chúc may mắn, Agent đồng nghiệp! Pipeline RAG đã hoạt động. Tiếp theo: DCE, Permission, Hardening.

4.9 KiB Raw Blame History