Tài liệu đầu vào (PDF, DOCX, XLSX, CSV, PPTX, HTML, Markdown, TXT, XML)
                                  │
                    ┌─────────────┴─────────────┐
                    ▼                           ▼
          Tầng 1: TRÍCH XUẤT            (Mỗi định dạng có
          (Format-Specific Extractors)   Extractor chuyên biệt)
                    │
                    ▼
          Tầng 2: MÔ HÌNH TÀI LIỆU CHUẨN
          DocumentModel { sections[], tables[], metadata }
                    │
       ┌────────────┼────────────────┐
       ▼            ▼                ▼
  Tầng 3a:     Tầng 3b:        Tầng 3c:
  XÁC THỰC     LƯU TRỮ BẢNG   CHIA ĐOẠN
  (Validation)  (DuckDB)       (Chunking)
       │                             │
       ▼                             ▼
  Báo cáo lỗi              Tầng 4: TÌM KIẾM NGỮ NGHĨA
  & cảnh báo               Qdrant Vector Store
                            - Dense + BM25 Sparse (RRF)
                            - Multilingual Cross-Encoder Reranker

# 1. Clone mã nguồn dự án
git clone https://github.com/nongtiensonpro/document-rag-mcp.git
cd document-rag-mcp

# 2. Tạo file cấu hình môi trường
cp .env.example .env

# 3. Đồng bộ và cài đặt toàn bộ thư viện phụ thuộc
uv sync

# 4. (Tùy chọn) Khởi chạy Qdrant qua Docker nếu dùng Docker mode
docker compose up -d qdrant

                  ┌─────────────────────────────────────┐
                  │          HERMES AGENT CORE          │
                  └──────────────────┬──────────────────┘
                                     │
           ┌─────────────────────────┴─────────────────────────┐
           ▼                                                   ▼
┌─────────────────────────────┐                     ┌─────────────────────────────┐
│  Cách A: Native User Plugin │                     │    Cách B: Std MCP Server   │
│   (~/.hermes/plugins/...)   │                     │      (config.yaml stdio)    │
│  - hermes plugins enable    │                     │  - Tự động spawn subprocess │
│  - Quản lý qua Desktop GUI  │                     │  - Chuẩn kết nối stdio JSON │
└─────────────────────────────┘                     └─────────────────────────────┘

# Xem danh sách plugin (document-rag sẽ xuất hiện trong danh sách)
hermes plugins list

# Bật plugin document-rag
hermes plugins enable document-rag

# Kiểm tra tính toàn vẹn (Diagnostics & Validation)
hermes plugins doctor document-rag

Plugin Doctor: ...\plugins\document-rag
  manifest: document-rag 0.3.0 (standalone)
  OK: runtime discovery, manifest parsing, import, and registration passed
  registrations: 14 tool(s), 0 hook(s)

hermes plugins disable document-rag

mcp_servers:
  document_rag:
    command: "uv"
    args:
      - "run"
      - "--project"
      - "D:/document-rag-mcp"       # ← Thay bằng đường dẫn tuyệt đối thư mục dự án của bạn
      - "document-rag-mcp"
    env:
      RAG_DOCUMENT_ROOT: "D:/document-rag-mcp/documents"
      QDRANT_URL: "http://localhost:6333"
      DUCKDB_PATH: "D:/document-rag-mcp/data/tables.duckdb"
      RAG_RULES_DIR: "D:/document-rag-mcp/rules"
      RAG_RERANKER_MODEL: "BAAI/bge-reranker-v2-m3"
      DENSE_MODEL: "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
      SPARSE_MODEL: "Qdrant/bm25"
      HYBRID_PREFETCH_LIMIT: "24"
      DEFAULT_LIMIT: "6"
      MAX_LIMIT: "20"
      RAG_LOG_LEVEL: "INFO"
      DOCLING_DO_OCR: "true"
      DOCLING_DO_TABLE_STRUCTURE: "true"
    enabled: true
    timeout: 300
    connect_timeout: 120
    supports_parallel_tool_calls: false
    tools:
      include:
        - index_document
        - index_directory
        - search_documents
        - query_tables
        - aggregate
        - list_tables
        - find_duplicates
        - reconcile_summary
        - list_documents
        - get_document
        - get_index_status
        - health
        - get_config
        - get_job_status
      resources: false
      prompts: false

{
  "mcpServers": {
    "document-rag": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "D:/document-rag-mcp",
        "document-rag-mcp"
      ],
      "env": {
        "RAG_DOCUMENT_ROOT": "D:/document-rag-mcp/documents",
        "DUCKDB_PATH": "D:/document-rag-mcp/data/tables.duckdb",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

index_document({
  "path": "reports/q3_finance.xlsx"
})

search_documents({
  "query": "chính sách bảo hành và điều khoản thanh toán",
  "limit": 5
})

// Bước 1: Liệt kê các bảng để lấy tên bảng và tên cột
list_tables()

// Bước 2: Chạy câu lệnh SQL chính xác
query_tables({
  "sql": "SELECT SUM(doanh_thu) AS tong_doanh_thu FROM t_a1b2c3d4_0 WHERE khu_vuc = 'Miền Bắc'"
})

// Bắt đầu tác vụ chạy ngầm
index_directory({
  "dir": "archive/2025",
  "async_index": true
})
// Trả về: { "job_id": "job_987654", "status": "running" }

// Kiểm tra tiến độ
get_job_status({
  "job_id": "job_987654"
})
// Trả về: { "status": "completed", "progress": { "processed": 45, "total": 45 } }

document-rag-mcp/
├── src/document_rag_mcp/
│   ├── server.py              # Entrypoint MCP server (khai báo 12 công cụ)
│   ├── rag.py                 # Pipeline điều phối chính (Extract → Validate → Store → Vector)
│   ├── config.py              # Đọc và resolve cấu hình độc lập CWD
│   ├── models.py              # Cấu trúc DocumentModel, Section, Table
│   ├── errors.py              # Định nghĩa mã lỗi chuẩn hóa
│   ├── utils.py               # Tiện ích tính hash, đường dẫn, text processing
│   ├── extractors/            # Tầng trích xuất đa định dạng
│   │   ├── base.py            #   Lớp trừu tượng BaseExtractor
│   │   ├── xlsx_extractor.py  #   Trích xuất Excel (.xlsx, .xls)
│   │   ├── csv_extractor.py   #   Trích xuất CSV (auto delimiter)
│   │   ├── docx_extractor.py  #   Trích xuất Word (.docx)
│   │   ├── pdf_extractor.py   #   Trích xuất PDF (Docling)
│   │   ├── pptx_extractor.py  #   Trích xuất PowerPoint (.pptx)
│   │   └── text_extractor.py  #   Trích xuất Markdown, TXT, HTML, XML
│   ├── validation/            # Tầng xác thực cấu trúc & dữ liệu
│   │   ├── engine.py          #   ValidationEngine & khử trùng lặp cảnh báo
│   │   ├── schema.py          #   ValidationRule, ValidationIssue schema
│   │   └── structural_rules.py#   Các quy tắc tự động (STT, summary, duplicate key)
│   ├── stores/                # Tầng lưu trữ
│   │   ├── table_store.py     #   DuckDB TableStore (bảo vệ SQL Read-Only)
│   │   └── vector_store.py    #   Qdrant Vector Store wrapper
│   ├── chunkers/              # Tầng chia nhỏ văn bản & bảng biểu
│   │   ├── table_chunker.py   #   Chia bảng (giữ header, row overlap)
│   │   └── text_chunker.py    #   Chia văn bản theo cấu trúc Heading
│   └── jobs/                  # Tầng quản lý tác vụ bất đồng bộ
│       ├── manager.py         #   JobManager (Thread pool)
│       └── worker.py          #   Hàm thực thi indexing worker
├── plugins/                   # Thư mục plugin đóng gói
│   └── document-rag/          #   Native Hermes Plugin (plugin.yaml, __init__.py)
├── rules/                     # Thư mục quy tắc kiểm tra JSON
│   └── _example.json          #   Mẫu khai báo quy tắc
├── documents/                 # Thư mục chứa tài liệu nạp mặc định
├── data/                      # Lưu trữ dữ liệu DuckDB & Qdrant local
├── tests/                     # Bộ kiểm thử tự động
│   ├── run_tests.py           #   Test runner thực thi
│   ├── test_models.py         #   Kiểm thử DocumentModel
│   ├── test_validation.py     #   Kiểm thử các quy tắc validation
│   ├── test_table_store.py    #   Kiểm thử DuckDB CRUD & SQL Read-Only
│   ├── test_chunkers.py       #   Kiểm thử chia đoạn bảng/văn bản
│   └── test_extractors.py     #   Kiểm thử các extractor
├── plugin.json                # Manifest chuẩn Portable Agent Plugins v1
├── mcp.json                   # Cấu hình MCP chuẩn Portable Agent Plugins v1
├── hermes.config.yaml.example # File cấu hình mẫu cho Hermes Agent
└── pyproject.toml             # Cấu hình gói và dependencies

uv run python tests/run_tests.py

============================================================
 Running Document RAG MCP Test Suite
============================================================

[test_models]
  [PASS] test_document_model_summary
  [PASS] test_section_hierarchy
  [PASS] test_table_operations

[test_validation]
  [PASS] test_cross_sheet_duplicate_keys
  [PASS] test_data_sheet_with_tong_prefix_not_misclassified_as_summary
  [PASS] test_duplicate_keys
  [PASS] test_filename_vs_content
  [PASS] test_required_any
  [PASS] test_required_not_empty
  [PASS] test_row_count_vs_declared_subsheet_and_grand_total
  [PASS] test_sequence_continuity_duplicate
  [PASS] test_sequence_continuity_gap
  [PASS] test_validation_engine_deduplication
  [PASS] test_validation_engine_with_rules

[test_table_store]
  [PASS] test_settings_path_resolution_independent_of_cwd
  [PASS] test_table_store_crud_and_query
  [PASS] test_table_store_strictly_read_only_queries

[test_chunkers]
  [PASS] test_table_chunker_header_once_and_overlap
  [PASS] test_text_chunker_sections

[test_extractors]
  [PASS] test_csv_extractor
  [PASS] test_markdown_extractor
  [PASS] test_xlsx_extractor_headerless_summary_sheet
  [PASS] test_xlsx_extractor_merged_title_banner

============================================================
 Tests: 23/23 passed (0 failed) in 0.83s
============================================================