README.md

metadata

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
   • 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:

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

POST /api/extract
Content-Type: multipart/form-data

Query Parameters:
- template_type: auto | payment_advice | invoice | custom_template

Example with curl:

curl -X POST "https://YOUR-SPACE.hf.space/api/extract?template_type=auto" \
  -F "file=@invoice.pdf"

Response:

{
  "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

GET /api/templates

Template Variations

GET /api/templates/variations

Flexible Naming

All these work identically:

?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)

// 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

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:

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

{"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

# 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):

# 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
• Issues: Create issue in your Space repository
• Community: Hugging Face Discord

Credits

Built with:

• Docling - Document processing
• FastAPI - Web framework
• Gradio - Web interface
• Pydantic - Data validation

---

Made with ❤️ for the document automation community