Spaces:
Sleeping
Sleeping
| title: Docling Multi-Template Extraction API | |
| emoji: 📄 | |
| colorFrom: blue | |
| colorTo: green | |
| sdk: docker | |
| pinned: false | |
| license: apache-2.0 | |
| # Docling Multi-Template Document Extraction API | |
| 🚀 Deploy Docling on Hugging Face Spaces with dynamic template matching for invoice and payment advice extraction. | |
| ## Features | |
| - 🔄 **Dynamic Template Discovery**: Automatically detects and loads templates from the `templates/` directory | |
| - 🎯 **Smart Name Matching**: Works with any naming convention (snake_case, kebab-case, PascalCase) | |
| - 🤖 **Auto-Detection**: Automatically identifies document types from content | |
| - 📊 **Structured JSON Output**: Extract invoices, payment advices, and custom documents to JSON | |
| - 🌐 **REST API**: Easy integration with n8n, Make, Zapier, or custom workflows | |
| - 🎨 **Web UI**: Built-in Gradio interface for testing | |
| ## Quick Start | |
| ### Deploy to Hugging Face Spaces | |
| 1. **Create a new Space:** | |
| - Go to [huggingface.co/spaces](https://huggingface.co/spaces) | |
| - Click "Create new Space" | |
| - Name: `docling-api` (or your preferred name) | |
| - SDK: **Docker** | |
| - Hardware: **CPU basic (free tier)** - 2 vCPU, 16 GB RAM | |
| 2. **Clone and push code:** | |
| ```bash | |
| git clone https://huggingface.co/spaces/YOUR-USERNAME/docling-api | |
| cd docling-api | |
| # Copy all files from this project | |
| # (app.py, templates/, requirements.txt, Dockerfile, README.md) | |
| git add . | |
| git commit -m "Initial deployment" | |
| git push | |
| ``` | |
| 3. **Wait for build** (5-10 minutes for first deployment) | |
| 4. **Your API is live at:** `https://YOUR-USERNAME-docling-api.hf.space` | |
| ## API Endpoints | |
| ### Extract Document Data | |
| ```http | |
| POST /api/extract | |
| Content-Type: multipart/form-data | |
| Query Parameters: | |
| - template_type: auto | payment_advice | invoice | custom_template | |
| ``` | |
| **Example with curl:** | |
| ```bash | |
| curl -X POST "https://YOUR-SPACE.hf.space/api/extract?template_type=auto" \ | |
| -F "file=@invoice.pdf" | |
| ``` | |
| **Response:** | |
| ```json | |
| { | |
| "success": true, | |
| "template_used": "invoice", | |
| "data": { | |
| "bill_no": "JRPL14725-26", | |
| "bill_date": "03-12-2025", | |
| "total_amount": 16618.0, | |
| "seller": { | |
| "name": "Jobuss Resources Pvt Ltd", | |
| "gst_no": "27AAECJ2353C1ZX" | |
| }, | |
| "buyer": { | |
| "name": "Reliance Industries Limited", | |
| "vendor_code": "3347687" | |
| } | |
| }, | |
| "filename": "invoice.pdf" | |
| } | |
| ``` | |
| ### List Available Templates | |
| ```http | |
| GET /api/templates | |
| ``` | |
| ### Template Variations | |
| ```http | |
| GET /api/templates/variations | |
| ``` | |
| ## Flexible Naming | |
| All these work identically: | |
| ```bash | |
| ?template_type=payment_advice # snake_case | |
| ?template_type=payment-advice # kebab-case | |
| ?template_type=PaymentAdvice # PascalCase | |
| ?template_type=PAYMENT_ADVICE # UPPER_CASE | |
| ``` | |
| ## Using with n8n | |
| ### Setup HTTP Request Node | |
| 1. **Method:** POST | |
| 2. **URL:** `https://YOUR-SPACE.hf.space/api/extract` | |
| 3. **Query Parameters:** | |
| - Name: `template_type` | |
| - Value: `auto` (or specific template name) | |
| 4. **Body Content Type:** Multipart-Form-Data | |
| 5. **Body Parameters:** | |
| - Name: `file` | |
| - Type: `n8n Binary File` | |
| - Input Data Field Name: `data` (or your binary field) | |
| ### Example n8n Workflow | |
| ``` | |
| [Trigger/File Input] | |
| ↓ | |
| [HTTP Request - Docling API] | |
| ↓ | |
| [Code Node - Parse Response] | |
| ↓ | |
| [Database/Spreadsheet Output] | |
| ``` | |
| ### Parse Response in Code Node (n8n) | |
| ```javascript | |
| // Access the extracted data | |
| const response = $input.item.json; | |
| if (response.success) { | |
| const data = response.data; | |
| return { | |
| invoice_number: data.bill_no, | |
| date: data.bill_date, | |
| amount: data.total_amount, | |
| vendor: data.seller?.name, | |
| all_data: data | |
| }; | |
| } | |
| ``` | |
| ## Adding Custom Templates | |
| Create a new file in `templates/` directory: | |
| ### Example: `templates/purchase_order_template.py` | |
| ```python | |
| from pydantic import BaseModel, Field | |
| from typing import Optional, List | |
| class POLineItem(BaseModel): | |
| item_code: Optional[str] = Field(default=None) | |
| description: Optional[str] = Field(default=None) | |
| quantity: Optional[float] = Field(default=None) | |
| unit_price: Optional[float] = Field(default=None) | |
| total: Optional[float] = Field(default=None) | |
| class Vendor(BaseModel): | |
| vendor_id: Optional[str] = Field(default=None) | |
| name: Optional[str] = Field(default=None) | |
| address: Optional[str] = Field(default=None) | |
| class PurchaseOrder(BaseModel): | |
| document_type: str = Field(default="purchase_order") | |
| po_number: Optional[str] = Field(default=None) | |
| po_date: Optional[str] = Field(default=None) | |
| delivery_date: Optional[str] = Field(default=None) | |
| vendor: Optional[Vendor] = Field(default=None) | |
| subtotal: Optional[float] = Field(default=None) | |
| tax_amount: Optional[float] = Field(default=None) | |
| total_amount: Optional[float] = Field(default=None) | |
| line_items: Optional[List[POLineItem]] = Field(default=[]) | |
| ``` | |
| **That's it!** The template is automatically discovered and available at: | |
| ``` | |
| ?template_type=purchase_order | |
| ``` | |
| ## Template Naming Convention | |
| File must follow this pattern: | |
| - **Filename:** `{template_name}_template.py` | |
| - **Class name:** PascalCase version of template_name (e.g., `PurchaseOrder`) | |
| - **Must inherit from:** `pydantic.BaseModel` | |
| Examples: | |
| - `payment_advice_template.py` → class `PaymentAdvice` | |
| - `invoice_template.py` → class `Invoice` | |
| - `purchase_order_template.py` → class `PurchaseOrder` | |
| ## Auto-Detection Keywords | |
| Edit `template_router.py` to add detection rules: | |
| ```python | |
| detection_rules = { | |
| "payment_advice": ["payment advice", "payment document"], | |
| "invoice": ["tax invoice", "bill no", "invoice date"], | |
| "purchase_order": ["purchase order", "po number"], | |
| "your_custom_type": ["your", "keywords", "here"], | |
| } | |
| ``` | |
| ## Web Interface | |
| Access the Gradio UI at: `https://YOUR-SPACE.hf.space/gradio` | |
| - Upload documents | |
| - Select template or use auto-detect | |
| - View extracted JSON instantly | |
| ## Supported Document Formats | |
| - PDF documents | |
| - Images (PNG, JPG, JPEG) | |
| - DOCX (requires additional configuration) | |
| ## Hardware Requirements | |
| ### Free Tier (CPU basic) | |
| - ✅ Standard invoices (1-5 pages) | |
| - ✅ Payment advices | |
| - ✅ Simple documents | |
| - ⚠️ Large PDFs may timeout (30s limit) | |
| ### Upgraded Tier (Recommended for production) | |
| - CPU basic upgrade: 4 vCPU, 16 GB RAM | |
| - Faster processing | |
| - Handle larger documents | |
| ## Troubleshooting | |
| ### Template Not Found Error | |
| ```json | |
| {"detail": "Template 'xyz' not found. Available templates: payment_advice, invoice"} | |
| ``` | |
| **Solution:** Check filename matches `{name}_template.py` pattern | |
| ### Timeout Errors | |
| **Solution:** Upgrade to larger hardware tier or reduce document size | |
| ### Import Errors | |
| **Solution:** Ensure all dependencies in `requirements.txt` and rebuild Space | |
| ## API Rate Limits | |
| Hugging Face Spaces free tier: | |
| - No official rate limit | |
| - Fair usage policy applies | |
| - For production: Consider Hugging Face Pro ($9/month) | |
| ## Local Development | |
| ```bash | |
| # Clone repository | |
| git clone https://huggingface.co/spaces/YOUR-USERNAME/docling-api | |
| cd docling-api | |
| # Install dependencies | |
| pip install -r requirements.txt | |
| # Run locally | |
| uvicorn app:app --host 0.0.0.0 --port 7860 --reload | |
| ``` | |
| Access at: `http://localhost:7860` | |
| ## Environment Variables | |
| Optional configurations (add in Space settings): | |
| ```bash | |
| # Logging level | |
| LOG_LEVEL=INFO | |
| # Max file size (MB) | |
| MAX_FILE_SIZE=50 | |
| ``` | |
| ## Security Notes | |
| - ⚠️ Free tier Spaces are public by default | |
| - 🔒 For sensitive documents, use private Spaces (Hugging Face Pro) | |
| - 🔐 Consider adding API key authentication for production | |
| ## Contributing | |
| Add new templates or improve detection logic: | |
| 1. Fork the Space | |
| 2. Add your template in `templates/` | |
| 3. Update detection rules in `template_router.py` | |
| 4. Test with sample documents | |
| 5. Submit pull request | |
| ## License | |
| Apache 2.0 | |
| ## Support | |
| - Documentation: [Docling GitHub](https://github.com/docling-project/docling) | |
| - Issues: Create issue in your Space repository | |
| - Community: Hugging Face Discord | |
| ## Credits | |
| Built with: | |
| - [Docling](https://github.com/docling-project/docling) - Document processing | |
| - [FastAPI](https://fastapi.tiangolo.com/) - Web framework | |
| - [Gradio](https://gradio.app/) - Web interface | |
| - [Pydantic](https://docs.pydantic.dev/) - Data validation | |
| --- | |
| **Made with ❤️ for the document automation community** |