Spaces:
Sleeping
Sleeping
| # README.md header for Hugging Face Spaces | |
| --- | |
| title: Advanced Document to Markdown Converter | |
| emoji: 🚀 | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: gradio | |
| sdk_version: 4.44.0 | |
| app_file: app.py | |
| pinned: true | |
| license: mit | |
| python_version: 3.11 | |
| hardware: cpu-basic | |
| tags: | |
| - document-processing | |
| - markdown | |
| - pdf-converter | |
| - ai-analysis | |
| - mcp-server-track | |
| - mcp-server | |
| - nlp | |
| - ocr | |
| short_description: Convert any document to Markdown with AI-powered analysis | |
| --- | |
| # 🚀 Advanced Document to Markdown Converter | |
| Convert documents to Markdown format with AI-powered analysis and advanced features. | |
| ## Features | |
| ### 📄 Supported Formats | |
| - **PDF** - With OCR support for image-based PDFs | |
| - **Word Documents** (.docx) - Full formatting preservation | |
| - **PowerPoint** (.pptx) - Slide-by-slide conversion | |
| - **Excel** (.xlsx) - Table extraction and formatting | |
| - **Plain Text** (.txt, .md) - Smart formatting detection | |
| - **Rich Text** (.rtf) - Complete formatting support | |
| - **E-books** (.epub) - Chapter and content extraction | |
| ### 🧠 AI-Powered Features | |
| - **Structure Analysis** - Intelligent document organization | |
| - **Topic Extraction** - Automatic keyword and topic identification | |
| - **Entity Recognition** - Named entity detection and classification | |
| - **Content Summarization** - AI-generated document summaries | |
| - **Smart Heading Detection** - Context-aware heading hierarchy | |
| ### ⚡ Advanced Capabilities | |
| - **Batch Processing** - Process multiple documents simultaneously | |
| - **OCR Integration** - Extract text from images and scanned documents | |
| - **Custom Templates** - Pre-configured output formats | |
| - **Caching System** - Improved performance for repeated processing | |
| - **Progress Tracking** - Real-time processing status | |
| - **Export Options** - Multiple output formats (MD, HTML, PDF) | |
| ### 🔧 Technical Features | |
| - **MCP Server** - Model Context Protocol integration | |
| - **Concurrent Processing** - Multi-threaded document handling | |
| - **Memory Optimization** - Efficient large file processing | |
| - **Error Recovery** - Robust error handling and reporting | |
| ## Usage | |
| ### Single Document Processing | |
| 1. Upload your document | |
| 2. Configure processing options | |
| 3. Click "Process Document" | |
| 4. View results in multiple tabs | |
| ### Batch Processing | |
| 1. Upload multiple documents | |
| 2. Enable combination option if needed | |
| 3. Process all documents simultaneously | |
| 4. Export results as needed | |
| ### MCP Integration | |
| This application can be used as an MCP server with Claude AI: | |
| ```json | |
| { | |
| "mcpServers": { | |
| "document_converter": { | |
| "command": "npx", | |
| "args": [ | |
| "mcp-remote", | |
| "https://YOUR-SPACE-URL/gradio_api/mcp/sse", | |
| "--transport", | |
| "sse-only" | |
| ] | |
| } | |
| } | |
| } | |
| ``` | |
| ## Installation | |
| ### Local Development | |
| ```bash | |
| git clone https://huggingface.co/spaces/YOUR-USERNAME/advanced-document-converter | |
| cd advanced-document-converter | |
| pip install -r requirements.txt | |
| python app.py | |
| ``` | |
| ### Docker Deployment | |
| ```dockerfile | |
| FROM python:3.11-slim | |
| WORKDIR /app | |
| COPY requirements.txt . | |
| RUN pip install -r requirements.txt | |
| # Install system dependencies for OCR | |
| RUN apt-get update && apt-get install -y \ | |
| tesseract-ocr \ | |
| tesseract-ocr-eng \ | |
| && rm -rf /var/lib/apt/lists/* | |
| COPY . . | |
| EXPOSE 7860 | |
| CMD ["python", "app.py"] | |
| ``` | |
| ## API Documentation | |
| ### Core Functions | |
| #### `process_document(file_path, options)` | |
| Process a single document and convert to Markdown. | |
| **Parameters:** | |
| - `file_path` (str): Path to the document file | |
| - `options` (dict): Processing configuration | |
| - `enable_ai_analysis` (bool): Enable AI-powered analysis | |
| - `include_frontmatter` (bool): Add YAML frontmatter | |
| - `generate_toc` (bool): Generate table of contents | |
| - `use_cache` (bool): Enable result caching | |
| **Returns:** | |
| - Dictionary with markdown content, structure analysis, and metadata | |
| #### `process_multiple_documents(file_paths, options)` | |
| Process multiple documents concurrently. | |
| **Parameters:** | |
| - `file_paths` (list): List of file paths | |
| - `options` (dict): Processing configuration | |
| - `combine_documents` (bool): Merge into single document | |
| - Additional options from single document processing | |
| **Returns:** | |
| - Dictionary with results for each document and optional combined output | |
| ### MCP Functions | |
| #### `extract_document_to_md_process_document` | |
| MCP-compatible function for document processing. | |
| **Parameters:** | |
| - `file_path` (str): HTTP/HTTPS URL to document | |
| - `show_prev` (bool): Return preview only | |
| - `show_struct` (bool): Include structure analysis | |
| ## Configuration | |
| ### Environment Variables | |
| - `MAX_FILE_SIZE_MB` - Maximum file size limit (default: 50) | |
| - `CACHE_DIR` - Directory for cached results | |
| - `WORKERS` - Number of concurrent workers | |
| - `ENABLE_OCR` - Enable OCR processing by default | |
| ### Processing Options | |
| - **AI Analysis**: Uses spaCy NLP models for advanced text analysis | |
| - **OCR**: Tesseract-based optical character recognition | |
| - **Caching**: Redis-compatible caching for improved performance | |
| ## Dependencies | |
| ### Core Requirements | |
| - `gradio>=4.0.0` - Web interface framework | |
| - `python-docx>=1.1.0` - Word document processing | |
| - `PyMuPDF>=1.23.0` - PDF processing | |
| - `python-pptx>=0.6.21` - PowerPoint processing | |
| - `openpyxl>=3.1.0` - Excel file processing | |
| ### AI/ML Requirements | |
| - `spacy>=3.7.0` - Natural language processing | |
| - `pytesseract>=0.3.10` - OCR capabilities | |
| - `transformers>=4.30.0` - Advanced AI models | |
| ### Optional Features | |
| - `matplotlib>=3.7.0` - Visualization capabilities | |
| - `pandas>=2.0.0` - Data processing | |
| - `scikit-learn>=1.3.0` - Machine learning features | |
| ## Performance | |
| ### Benchmarks | |
| - **Small files** (<1MB): ~2-5 seconds | |
| - **Medium files** (1-10MB): ~10-30 seconds | |
| - **Large files** (10-50MB): ~30-120 seconds | |
| - **Batch processing**: Linear scaling with concurrent workers | |
| ### Memory Usage | |
| - **Base memory**: ~200MB | |
| - **Per document**: ~50-100MB additional | |
| - **OCR processing**: +200-500MB peak usage | |
| ## Contributing | |
| 1. Fork the repository | |
| 2. Create feature branch: `git checkout -b feature-name` | |
| 3. Commit changes: `git commit -am 'Add feature'` | |
| 4. Push to branch: `git push origin feature-name` | |
| 5. Submit pull request | |
| ## License | |
| MIT License - see LICENSE file for details. | |
| ## Support | |
| - **Issues**: Report bugs and feature requests on GitHub | |
| - **Documentation**: Full API documentation available | |
| - **Community**: Join discussions in the Community tab | |
| --- | |
| *Built with ❤️ using Gradio, spaCy, and various document processing libraries* |