Spaces:
Runtime error
Runtime error
| title: Markit_v2 | |
| emoji: 📄 | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: gradio | |
| sdk_version: 5.14.0 | |
| app_file: app.py | |
| build_script: build.sh | |
| startup_script: setup.sh | |
| pinned: false | |
| hf_oauth: true | |
| # Document to Markdown Converter with RAG Chat | |
| **Author: Anse Min** | [🤗 Hugging Face Space](https://huggingface.co/spaces/Ansemin101/Markit_v2) | [GitHub](https://github.com/ansemin/Markit_v2) | [LinkedIn](https://www.linkedin.com/in/ansemin/) | |
| A powerful Hugging Face Space that converts various document formats to Markdown and enables intelligent chat with your documents using advanced RAG (Retrieval-Augmented Generation). | |
| ## 🎥 Demo Video | |
| <div align="center"> | |
| <a href="https://www.youtube.com/watch?v=PmXu3Si6hXo"> | |
| <img src="https://img.youtube.com/vi/PmXu3Si6hXo/maxresdefault.jpg" alt="Markit Demo Video" width="600"> | |
| </a> | |
| **[▶️ Watch Full Demo (YouTube)](https://www.youtube.com/watch?v=PmXu3Si6hXo)** | |
| *Complete walkthrough of Markit's flagship features including multi-document processing, RAG chat, and advanced retrieval strategies* | |
| </div> | |
| <details> | |
| <summary><strong>Table of contents</strong></summary> | |
| <!-- Begin ToC --> | |
| - [Demo Video](#-demo-video) | |
| - [Live Demos](#-live-demos) | |
| - [System Overview](#-system-overview) | |
| - [Environment Setup](#-environment-setup) | |
| - [Local Development](#-local-development) | |
| - [Technical Details](#-technical-details) | |
| <!-- End ToC --> | |
| </details> | |
| ## 🎬 Live Demos | |
| ### 1. Multi-Document Processing (Flagship Feature) | |
| <div align="center"> | |
| <img src="GIF/Multi-Document Processing Showcase.gif" alt="Multi-Document Processing Demo" width="800"> | |
| </div> | |
| **What it does:** Process up to 5 files simultaneously (20MB combined) with 4 intelligent processing types: | |
| - **🔗 Combined**: Merge documents with smart duplicate removal | |
| - **📑 Individual**: Separate sections per document with clear organization | |
| - **📈 Summary**: Executive overview + detailed analysis of all documents | |
| - **⚖️ Comparison**: Cross-document analysis with similarities/differences tables | |
| **Why it matters:** Industry-leading multi-document processing that compares and contrasts information across different files, handles mixed file types seamlessly, and recognizes relationships across document boundaries. | |
| <div align="center"> | |
| <img src="img/Multi-Document Processing Types (Flagship Feature).png" alt="Multi-Document Processing Types" width="700"> | |
| *Industry-leading multi-document processing with 4 intelligent processing types* | |
| </div> | |
| ### 2. Single Document Conversion Flow | |
| <div align="center"> | |
| <img src="GIF/Single Document Conversion Flow.gif" alt="Single Document Conversion Demo" width="800"> | |
| </div> | |
| **What it does:** Convert PDFs, Office documents, images, and more to Markdown using 5 powerful parsers: | |
| - **Gemini Flash**: AI-powered understanding with high accuracy | |
| - **Mistral OCR**: Fastest processing with document understanding | |
| - **Docling**: Open source with advanced PDF table recognition | |
| - **GOT-OCR**: Mathematical/scientific documents to LaTeX | |
| - **MarkItDown**: High accuracy for CSV/XML and broad format support | |
| **Why it matters:** Perfect table preservation creates enhanced markdown tables for superior RAG context, unlike standard PDF text extraction. | |
| <div align="center"> | |
| <img src="img/Parser Selection Guide (User-Friendly).png" alt="Parser Selection Guide" width="700"> | |
| *Choose the right parser for your specific needs and document types* | |
| </div> | |
| ### 3. RAG Chat System in Action | |
| <div align="center"> | |
| <img src="GIF/RAG Chat System in Action.gif" alt="RAG Chat System Demo" width="800"> | |
| </div> | |
| **What it does:** Chat with your converted documents using 4 advanced retrieval strategies: | |
| - **🎯 Similarity**: Traditional semantic similarity using embeddings | |
| - **🔀 MMR**: Diverse results with reduced redundancy | |
| - **🔍 BM25**: Traditional keyword-based retrieval | |
| - **🔗 Hybrid**: Combines semantic + keyword search (recommended) | |
| **Why it matters:** Ask for markdown tables in chat responses (impossible with standard PDF RAG), get streaming responses with document context, and easily clear data directly from the interface. | |
| <div align="center"> | |
| <img src="img/RAG Retrieval Strategies (Technical Highlight).png" alt="RAG Retrieval Strategies" width="700"> | |
| *Advanced RAG system with 4 retrieval strategies for optimal document search* | |
| </div> | |
| ### 4. Query Ranker Analysis | |
| <div align="center"> | |
| <img src="GIF/Query Ranker Analysis.gif" alt="Query Ranker Demo" width="800"> | |
| </div> | |
| **What it does:** Interactive document search with: | |
| - **Real-time ranking** of document chunks with confidence scores | |
| - **Method comparison** to test different retrieval strategies | |
| - **Adjustable results** (1-10) with responsive slider control | |
| - **Transparent scoring** with actual ChromaDB similarity scores | |
| **Why it matters:** Provides complete transparency into how your RAG system finds and ranks information, helping you optimize retrieval strategies. | |
| ### 5. GOT-OCR LaTeX Processing | |
| <div align="center"> | |
| <img src="GIF/GOT-OCR LaTeX Processing.gif" alt="GOT-OCR LaTeX Demo" width="800"> | |
| </div> | |
| **What it does:** Advanced LaTeX processing for mathematical and scientific documents: | |
| - **Native LaTeX output** with no LLM conversion for maximum accuracy | |
| - **Mathpix rendering** using the same library as official GOT-OCR demo | |
| - **RAG-compatible chunking** that preserves LaTeX structures and mathematical tables | |
| - **Professional display** with proper mathematical formatting | |
| **Why it matters:** Perfect for research papers, scientific documents, and academic content with complex equations and structured data. | |
| ## 🎯 System Overview | |
| <div align="center"> | |
| <img src="img/Overall%20System%20Workflow%20(Essential).png" alt="Overall System Workflow" width="600"> | |
| *Complete workflow from document upload to intelligent RAG chat interaction* | |
| </div> | |
| ## 🔧 Environment Setup | |
| ### Required API Keys | |
| ```bash | |
| GOOGLE_API_KEY=your_gemini_api_key_here # For Gemini Flash parser and RAG chat | |
| OPENAI_API_KEY=your_openai_api_key_here # For embeddings and AI descriptions | |
| MISTRAL_API_KEY=your_mistral_api_key_here # For Mistral OCR parser (optional) | |
| ``` | |
| ### Key Configuration Options | |
| ```bash | |
| DEBUG=true # Enable debug logging | |
| MAX_FILE_SIZE=10485760 # 10MB per file limit | |
| MAX_BATCH_FILES=5 # Maximum files for multi-document processing | |
| MAX_BATCH_SIZE=20971520 # 20MB combined limit for batch processing | |
| CHUNK_SIZE=1000 # Document chunk size for Markdown content | |
| RETRIEVAL_K=4 # Number of documents to retrieve for RAG | |
| ``` | |
| ## 🚀 Local Development | |
| ### Quick Start | |
| ```bash | |
| # Clone repository | |
| git clone https://github.com/ansemin/Markit_v2 | |
| cd Markit_v2 | |
| # Create environment file | |
| cp .env.example .env | |
| # Edit .env with your API keys | |
| # Install dependencies | |
| pip install -r requirements.txt | |
| # Run application | |
| python app.py # Full environment setup (HF Spaces compatible) | |
| python run_app.py # Local development (faster startup) | |
| python run_app.py --clear-data-and-run # Testing with clean data | |
| ``` | |
| ### Data Management | |
| **Two ways to clear data:** | |
| 1. **UI Method**: Chat tab → "🗑️ Clear All Data" button (works in both local and HF Space) | |
| 2. **CLI Method**: `python run_app.py --clear-data-and-run` | |
| **What gets cleared:** Vector store embeddings, chat history, and session data | |
| ## 🔍 Technical Details | |
| ### Retrieval Strategy Performance | |
| | Method | Best For | Accuracy | | |
| |--------|----------|----------| | |
| | **🎯 Similarity** | General semantic questions | Good | | |
| | **🔀 MMR** | Diverse perspectives | Good | | |
| | **🔍 BM25** | Exact keyword searches | Medium | | |
| | **🔗 Hybrid** | Most queries (recommended) | **Excellent** | | |
| ### Core Technologies | |
| - **Parsers**: Gemini Flash, Mistral OCR, Docling, GOT-OCR, MarkItDown | |
| - **RAG System**: OpenAI embeddings + ChromaDB vector store + Gemini 2.5 Flash | |
| - **UI Framework**: Gradio with modular component architecture | |
| - **GPU Support**: ZeroGPU integration for HF Spaces | |
| ### Smart Content-Aware Chunking | |
| - **Markdown chunking**: Preserves tables and code blocks | |
| - **LaTeX chunking**: Preserves mathematical tables, environments, and structures | |
| - **Automatic format detection**: Optimal chunking strategy per document type | |
| ## Credits | |
| - [MarkItDown](https://github.com/microsoft/markitdown) by Microsoft | |
| - [Docling](https://github.com/DS4SD/docling) by IBM Research | |
| - [GOT-OCR](https://github.com/stepfun-ai/GOT-OCR-2.0) by StepFun | |
| - [Mathpix Markdown](https://github.com/Mathpix/mathpix-markdown-it) for LaTeX rendering | |
| - [Gradio](https://gradio.app/) for the UI framework | |
| --- | |
| **🚀 [Try it live on Hugging Face Spaces](https://huggingface.co/spaces/Ansemin101/Markit_v2)** |