README.md

---
title: Docling Document Processor
emoji: 📄
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: "4.44.1"
app_file: app.py
pinned: false
license: mit
short_description: Processe documentos PDF/DOC/DOCX com IA
---

# 📄 Docling Document Processor

Aplicação Gradio para processamento de documentos usando [Docling](https://github.com/docling-project/docling) com aceleração ZeroGPU.

![Gradio](https://img.shields.io/badge/Gradio-4.44+-orange)
![Python](https://img.shields.io/badge/Python-3.10+-blue)
![License](https://img.shields.io/badge/License-MIT-green)

## ✨ Recursos

- 🔍 **Extração inteligente** de texto, tabelas e metadados
- 🌐 **Detecção automática** de idioma
- 🚀 **Aceleração GPU** via ZeroGPU (Hugging Face Spaces)
- 📊 **Preserva estrutura** hierárquica do documento
- 📁 **Upload múltiplo** (1-5 arquivos simultâneos)
- 🔒 **Segurança** com validação de MIME type e sanitização

## 📋 Formatos Suportados

| Entrada | Saída |
|---------|-------|
| PDF | JSON |
| DOC | Markdown |
| DOCX | ZIP (ambos) |

## 🚀 Instalação Local

### Pré-requisitos

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recomendado) ou pip

### Com uv

```bash
# Clone o repositório
git clone https://huggingface.co/spaces/SEU_USUARIO/docling-processor
cd docling-processor

# Crie ambiente virtual e instale dependências
uv venv
source .venv/bin/activate  # Linux/macOS
uv pip install -r requirements.txt

# Execute
python app.py
```

### Com pip

```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python app.py
```

Acesse: http://localhost:7860

## 🌐 Deploy no Hugging Face Spaces

### 1. Crie o Space

```bash
# Login no Hugging Face
hf login

# Crie o Space (substitua SEU_USUARIO pelo seu username)
hf repo create SEU_USUARIO/docling-processor --repo-type space --space-sdk gradio
```

### 2. Configure ZeroGPU

No Hugging Face, vá em **Settings > Hardware** e selecione **ZeroGPU**.

### 3. Push do código

```bash
cd /caminho/para/docling_hf
git remote add space https://huggingface.co/spaces/SEU_USUARIO/docling-processor
git push space main
```

### 4. Verifique

Acesse: `https://huggingface.co/spaces/SEU_USUARIO/docling-processor`

## 📂 Estrutura do Projeto

```
docling_hf/
├── app.py                 # Interface Gradio + ZeroGPU
├── config.py              # Configurações centralizadas
├── requirements.txt       # Dependências
├── README.md              # Esta documentação
├── processors/            # Lógica de processamento
│   ├── docling_processor.py
│   ├── json_formatter.py
│   └── markdown_formatter.py
├── utils/                 # Utilitários
│   ├── validators.py
│   ├── file_handler.py
│   └── logger.py
├── tests/                 # Testes unitários
│   └── test_processors.py
└── logs/                  # Arquivos de log
```

## 📤 Formatos de Saída

### JSON

```json
{
  "arquivo": "documento.pdf",
  "idioma": "pt",
  "processado_em": "2024-01-15T10:30:00",
  "metadados": {
    "nome_arquivo": "documento.pdf",
    "num_paginas": 5,
    "num_tabelas": 2
  },
  "tabelas": [...],
  "conteudo": {...}
}
```

### Markdown

```markdown
# Título do Documento

**Autor:** João Silva
**Idioma:** Português
**Páginas:** 5

---

## Conteúdo

[Texto extraído do documento...]

---

## Tabelas Extraídas

| Coluna 1 | Coluna 2 |
|----------|----------|
| Valor 1  | Valor 2  |
```

## ⚙️ Configuração

Edite `config.py` para personalizar:

| Variável | Padrão | Descrição |
|----------|--------|-----------|
| `MAX_FILE_SIZE_MB` | 50 | Limite por arquivo |
| `MAX_FILES_PER_SESSION` | 5 | Arquivos por upload |
| `PROCESSING_TIMEOUT_SECONDS` | 300 | Timeout de processamento |
| `RATE_LIMIT_REQUESTS` | 10 | Requisições por hora |

## 🧪 Testes

```bash
# Executar testes
python -m pytest tests/ -v

# Com cobertura
python -m pytest tests/ -v --cov=. --cov-report=html
```

## 🔧 Troubleshooting

### ❌ "Arquivo muito grande"

Reduza o tamanho do PDF ou divida em partes menores.

### ❌ "Tipo de arquivo inválido"

Verifique se o arquivo não está corrompido. O sistema valida o conteúdo real, não apenas a extensão.

### ❌ "Timeout"

- Arquivos muito grandes ou complexos podem exceder o limite
- Tente processar menos arquivos por vez
- PDFs escaneados (OCR) levam mais tempo

### ❌ "Rate limit excedido"

Aguarde 1 hora ou use uma conta diferente.

## 📄 Licença

MIT License - veja [LICENSE](LICENSE) para detalhes.

## 🤝 Contribuições

Contribuições são bem-vindas! Abra uma issue ou pull request.

---

Desenvolvido com ❤️ usando [Docling](https://github.com/docling-project/docling) e [Gradio](https://gradio.app)