⚡ MarkItDown Advanced (GUI & CLI)

A powerful batch Markdown converter for documents and images with optional local Baidu/Qwen Vision AI OCR and Dynamic GPU VRAM Auto-Scaling.

Powered by Microsoft's MarkItDown and llama.cpp.

---

✨ Features

• Multi-Format Document Parsing: Convert .docx, .xlsx, .csv, .pptx, .pdf, .html, .json, .xml, .eml, .zip, and image formats (.jpg, .png, .webp) into clean Markdown files.
• Local Vision AI OCR (Advanced Mode): Uses sahilchachra/Unlimited-OCR-GGUF (Baidu/Qwen architecture) via llama-cpp-python for deep visual text and table extraction from scanned PDFs and images.
• Dynamic GPU VRAM Auto-Scaling:
  • Automatically checks NVIDIA VRAM using nvidia-smi.
  • Full Acceleration on GPUs with 3.8GB+ VRAM (n_gpu_layers=-1).
  • Partial Offloading on lower-spec GPUs (1.5GB to 3.8GB VRAM) by dynamically splitting transformer layers between VRAM and System RAM to prevent crashes.
  • Safe fallbacks and status reporting for hardware limits.
• Dual Interface:
  • GUI App (Advanced/advanced_convert_gui.py): Clean, compact Tkinter interface with docked bottom control panel, 2-column checklist grid, and side-by-side progress bars.
  • CLI Tool (cli/convert_cli.py): Non-interactive command-line flags mode + step-by-step interactive terminal prompt mode.
• Zero-Touch Dependency Setup: Automatically verifies requirements and installs missing packages/wheels with progress feedback before launch.

---

📁 Repository Structure

MarkItDown-Advanced/
├── Advanced/                  # GUI Application
│   ├── advanced_convert_gui.py# Main GUI application entrypoint
│   ├── advanced_ocr_engine.py # AI OCR & VRAM hardware calculation engine
│   └── requirements.txt       # GUI dependencies
├── cli/                       # Command-Line Application
│   ├── convert_cli.py         # Main CLI tool script (flags & interactive prompts)
│   ├── advanced_ocr_engine.py # Shared AI OCR & VRAM hardware calculation engine
│   └── requirements.txt       # CLI dependencies
├── .gitignore
└── README.md

---

🚀 Quick Start

Prerequisites

• Python: 3.10, 3.11, or 3.12 (64-bit)
• NVIDIA GPU (Optional for Advanced AI OCR): Recommended 2GB+ VRAM for hardware acceleration. Standard conversion runs on any CPU without GPU.

---

1. Running the GUI Application

cd Advanced
python advanced_convert_gui.py

• Select your Source Folder and Destination Folder.
• Check Use Baidu Unlimited-OCR for PDFs and Images if you want deep Vision AI OCR.
• Click Start Conversion.

---

2. Running the CLI Tool

Command-Line Flags Mode (Non-Interactive):

cd cli

# Enable Advanced AI OCR & Preserve Subfolder Hierarchy
python convert_cli.py -s "C:/path/to/source" -d "C:/path/to/destination" --ocr --structure

# Standard Conversion without AI OCR (Fast Mode)
python convert_cli.py -s "C:/path/to/source" -d "C:/path/to/destination" --no-ocr --flat

Interactive Prompt Mode:

Simply run convert_cli.py without arguments:

cd cli
python convert_cli.py

Follow the step-by-step interactive prompts on your terminal.

CLI Arguments Reference:

Option	Short	Description
--source <path>	-s	Path to the source input folder
--destination <path>	-d	Path to destination folder (default: source/AI)
--ocr / --qwen-ocr		Enable Advanced Vision AI OCR
--no-ocr / --no-qwen-ocr		Disable Advanced Vision AI OCR
--structure		Preserve source folder hierarchy inside destination
--flat		Flatten all output .md files into a single folder
--interactive	-i	Force interactive step-by-step terminal prompt

---

🛠️ Dependencies & Hardware Acceleration

The project relies on prebuilt CUDA wheels for llama-cpp-python. Dependencies are listed in requirements.txt:

--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124
markitdown
huggingface_hub
pymupdf
pillow
llama-cpp-python

Model weights (Unlimited-OCR-Q4_K_M.gguf & mmproj-Unlimited-OCR-F16.gguf) are automatically fetched from Hugging Face Hub on first use and stored in %APPDATA%/MarkItDown_GUI/models.

---

📜 License

Distributed under the MIT License.