Apppublic

imran-decoder/filecrackhead1

sourceHugging Faceupdated 6mo agoView on Hugging Face

0likes

App README

📄 File Conversion Service

A production-ready FastAPI REST API for converting documents between 30+ format pairs. Deploy to Hugging Face Spaces with Docker in minutes.

![FastAPI](https://fastapi.tiangolo.com) ![Python](https://python.org) ![Docker](https://docker.com)

✨ Features

Category	Formats
PDF ↔ Office	PDF ↔ DOCX, DOC, ODT, RTF
PDF ↔ Images	PDF → JPG, PNG
PDF ↔ Text	PDF ↔ TXT, HTML, EPUB
Word	DOCX ↔ PDF/TXT/ODT/RTF/HTML, DOC ↔ DOCX/PDF/TXT
PowerPoint	PPT/PPTX ↔ PDF, PPTX → JPG
Spreadsheet	XLSX/XLS ↔ PDF
Text & Markup	TXT/HTML/Markdown ↔ PDF/DOCX
eBook	EPUB ↔ PDF/DOCX/TXT

🔍 Premium OCR (PDF → DOCX)

Two modes for PDF → DOCX:

Mode	Endpoint Param	Speed	Use Case
Free (text-layer)	`use_ocr=false` (default)	~1s	Native text PDFs
Premium OCR	`use_ocr=true`	~10-60s/page	Scanned/image PDFs

Gate use_ocr=true behind your own billing/auth middleware to charge for OCR.

🚀 Quick Start

Local Development

bash

# 1. Clone and set up
git clone <repo-url> && cd file_converter

# 2. Create a virtual environment
python -m venv .venv && source .venv/bin/activate

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Install system tools (macOS / Ubuntu shown)
# macOS
brew install libreoffice pandoc poppler ghostscript tesseract

# Ubuntu/Debian
sudo apt-get install libreoffice pandoc poppler-utils ghostscript tesseract-ocr

# 5. Configure environment
cp .env.example .env

# 6. Run the server
uvicorn app.main:app --reload --port 8000

Open http://localhost:8000/docs for Swagger UI.

Run Tests

bash

pytest tests/ -v
# Skip slow integration tests
pytest tests/ -v -m "not slow"

🐳 Docker

Build & Run Locally

bash

docker build -t file-converter .
docker run -p 7860:7860 \
  -e MAX_FILE_SIZE_MB=25 \
  -e RATE_LIMIT_PER_MINUTE=10 \
  file-converter

Open http://localhost:7860/docs

Environment Variables

Variable	Default	Description
`MAX_FILE_SIZE_MB`	`25`	Max upload size
`RATE_LIMIT_PER_MINUTE`	`10`	Rate limit per IP
`LOG_LEVEL`	`INFO`	Logging level
`LOG_FORMAT`	`json`	`json` or `text`
`OCR_LANGUAGE`	`eng`	Tesseract language(s)
`OCR_DPI`	`300`	OCR render DPI (150–600)
`LIBREOFFICE_PATH`	`soffice`	Path to LibreOffice
`PANDOC_PATH`	`pandoc`	Path to pandoc
`TESSERACT_PATH`	`/usr/bin/tesseract`	Path to tesseract

🌍 Deploy to Hugging Face Spaces

1.Create a new Space on huggingface.co/spaces
2.Select Docker as the SDK
3.Push this repository to the Space

bash

git remote add hf https://huggingface.co/spaces/<username>/<space-name>
git push hf main

1.The Space will automatically build the Docker image and expose on port 7860.

Note: Hugging Face Spaces provides ~2vCPU and 16GB RAM on free tier. OCR on large scanned PDFs may be slow — consider upgrading hardware for production OCR workloads.

📡 API Reference

`POST /convert`

Convert a document file.

Form fields: | Field | Type | Required | Description | |---|---|---|---| | file | UploadFile | ✅ | Source document | | target_format | string | ✅ | Target format (e.g. docx, pdf) | | use_ocr | bool | ❌ | Enable OCR pipeline (default: false) | | ocr_language | string | ❌ | Tesseract language code (default: eng) | | ocr_dpi | int | ❌ | OCR render DPI, 72–600 (default: 300) |

Example (curl):

bash

# Free tier: text-layer extraction
curl -X POST http://localhost:7860/convert \
  -F "file=@document.pdf" \
  -F "target_format=docx" \
  --output converted.docx

# Premium: OCR pipeline for scanned PDFs
curl -X POST http://localhost:7860/convert \
  -F "file=@scanned.pdf" \
  -F "target_format=docx" \
  -F "use_ocr=true" \
  -F "ocr_language=eng" \
  --output ocr_output.docx

Response headers:

—X-Source-Format — detected source format
—X-Target-Format — target format used
—X-OCR-Used — whether OCR was applied (true/false)
—X-Output-Size-Bytes — output file size

`GET /health`

Returns service status and tool availability.

`GET /formats`

Returns all supported (source → target) pairs grouped by source format.

🏗️ Project Structure

file_converter/
├── app/
│   ├── main.py               # FastAPI app factory
│   ├── config.py             # Settings (env-driven)
│   ├── validators.py         # Conversion matrix & Pydantic models
│   ├── routers/
│   │   ├── convert.py        # POST /convert
│   │   ├── health.py         # GET /health
│   │   └── formats.py        # GET /formats
│   ├── services/
│   │   ├── conversion_engine.py    # Central dispatcher
│   │   ├── ocr_converter.py        # ⭐ PDF→DOCX free+OCR (premium)
│   │   ├── pdf_converter.py        # PDF conversions
│   │   ├── word_converter.py       # Word conversions
│   │   ├── pptx_converter.py       # PowerPoint conversions
│   │   ├── spreadsheet_converter.py# Spreadsheet conversions
│   │   ├── text_converter.py       # TXT/HTML/MD conversions
│   │   └── ebook_converter.py      # EPUB conversions
│   ├── security/
│   │   ├── file_validator.py       # MIME, size, encryption checks
│   │   ├── rate_limiter.py         # SlowAPI rate limiting
│   │   └── sanitizer.py            # Filename sanitization
│   └── utils/
│       ├── file_utils.py           # Temp dir management
│       └── logging_utils.py        # Structured JSON logging
├── tests/
│   ├── conftest.py
│   ├── test_validators.py
│   ├── test_conversion_engine.py
│   └── test_api.py
├── Dockerfile
├── requirements.txt
├── .env.example
└── .dockerignore

🔐 Security

—✅ MIME type validation via magic bytes
—✅ File extension whitelist
—✅ 25MB size limit (configurable)
—✅ PDF encryption/password detection
—✅ Filename sanitization (UUID prefix + pathvalidate)
—✅ Path traversal prevention
—✅ Per-IP rate limiting (SlowAPI)
—✅ Temp files auto-deleted after every request (even on failure)
—✅ Non-root Docker user
—✅ Global exception handler (no stack trace leaks)

📊 OCR Quality Tips

DPI	Quality	Use Case
150	Fast / low	Quick drafts, well-scanned docs
300	Recommended	Standard scanned documents
600	Slow / high	Fine print, forms, low-quality scans

For multi-language documents, combine codes: ocr_language=eng+fra+ara

📝 License

MIT License — see LICENSE file.