feat: Docling Document Processor - Gradio + ZeroGPU

- Interface para upload múltiplo (1-5 arquivos)
- Suporte a PDF, DOC, DOCX (até 50MB)
- Saída em JSON, Markdown ou ZIP (ambos)
- Aceleração GPU via @spaces.GPU
- Rate limiting, logging e validação robusta

README.md

@@ -1,12 +1,203 @@
+# 📄 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...]
+
 ---
-title: Docling Processor
-emoji: 🏢
-colorFrom: yellow
-colorTo: pink
-sdk: gradio
-sdk_version: 6.0.2
-app_file: app.py
-pinned: false
+
+## 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.
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Desenvolvido com ❤️ usando [Docling](https://github.com/docling-project/docling) e [Gradio](https://gradio.app)

app.py

@@ -0,0 +1,491 @@
+"""
+Docling Document Processor - Aplicação Principal.
+
+Este é o ponto de entrada da aplicação Gradio que permite
+o upload e processamento de documentos usando Docling.
+
+Recursos:
+- Upload múltiplo (1-5 arquivos)
+- Formatos: PDF, DOC, DOCX
+- Saída: JSON, Markdown ou ambos (ZIP)
+- Aceleração GPU via ZeroGPU
+"""
+
+import os
+import sys
+import time
+import traceback
+from collections import defaultdict
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+import gradio as gr
+
+# Importação condicional do spaces para ZeroGPU
+try:
+    import spaces
+    HAS_SPACES = True
+except ImportError:
+    HAS_SPACES = False
+
+# Adiciona o diretório atual ao path para imports locais
+sys.path.insert(0, str(Path(__file__).parent))
+
+import config
+from utils.validators import validate_files, ValidationError
+from utils.file_handler import (
+    create_temp_directory,
+    cleanup_old_files,
+    create_zip_output,
+    save_output_file,
+)
+from utils.logger import setup_logger, get_logger
+from processors.docling_processor import DoclingProcessor
+from processors.json_formatter import format_to_json, JSONFormatter
+from processors.markdown_formatter import format_to_markdown, MarkdownFormatter
+
+# Configura logger
+logger = setup_logger("docling_space")
+
+# =============================================================================
+# RATE LIMITING (in-memory)
+# =============================================================================
+
+# Armazena requisições por IP: {ip: [timestamps]}
+_rate_limit_store: dict[str, list[datetime]] = defaultdict(list)
+
+
+def check_rate_limit(request: gr.Request) -> bool:
+    """
+    Verifica se o IP excedeu o limite de requisições.
+
+    Args:
+        request: Objeto de request do Gradio.
+
+    Returns:
+        True se está dentro do limite, False se excedeu.
+    """
+    if request is None:
+        return True
+
+    # Obtém IP do cliente
+    client_ip = getattr(request, "client", {})
+    if isinstance(client_ip, dict):
+        ip = client_ip.get("host", "unknown")
+    else:
+        ip = str(client_ip)
+
+    now = datetime.now()
+    window_start = now - timedelta(hours=config.RATE_LIMIT_WINDOW_HOURS)
+
+    # Limpa requisições antigas
+    _rate_limit_store[ip] = [
+        ts for ts in _rate_limit_store[ip]
+        if ts > window_start
+    ]
+
+    # Verifica limite
+    if len(_rate_limit_store[ip]) >= config.RATE_LIMIT_REQUESTS:
+        logger.warning(f"Rate limit excedido para IP: {ip}")
+        return False
+
+    # Registra nova requisição
+    _rate_limit_store[ip].append(now)
+    return True
+
+
+# =============================================================================
+# FUNÇÃO DE PROCESSAMENTO PRINCIPAL
+# =============================================================================
+
+def _process_documents_internal(
+    files: list,
+    output_format: str,
+    progress: Optional[gr.Progress] = None
+) -> tuple[str | list[str], str]:
+    """
+    Função interna de processamento (sem decorator GPU).
+
+    Args:
+        files: Lista de arquivos enviados.
+        output_format: Formato de saída ("JSON", "Markdown", "Ambos").
+        progress: Objeto de progresso do Gradio.
+
+    Returns:
+        Tupla (caminho(s) do arquivo de saída, mensagem de status).
+    """
+    start_time = time.time()
+
+    # Limpa arquivos temporários antigos
+    cleanup_old_files()
+
+    # Valida arquivos
+    if progress:
+        progress(0.1, desc="Validando arquivos...")
+
+    try:
+        validated_files = validate_files(files)
+    except ValidationError as e:
+        logger.warning(f"Erro de validação: {e.message}")
+        raise gr.Error(e.message)
+
+    # Prepara processador
+    if progress:
+        progress(0.2, desc="Inicializando Docling...")
+
+    processor = DoclingProcessor(
+        enable_ocr=True,
+        enable_table_detection=True,
+        use_gpu=HAS_SPACES
+    )
+
+    # Cria diretório de saída
+    output_dir = create_temp_directory(prefix="output_")
+    output_files = []
+    processed_count = 0
+    total_files = len(validated_files)
+
+    # Processa cada arquivo
+    for i, (file_path, sanitized_name) in enumerate(validated_files):
+        progress_pct = 0.2 + (0.6 * (i / total_files))
+
+        if progress:
+            progress(progress_pct, desc=f"Processando {sanitized_name}...")
+
+        try:
+            # Processa documento
+            processed_data = processor.process_document(file_path)
+
+            # Gera nome base sem extensão
+            base_name = Path(sanitized_name).stem
+
+            # Formata saída
+            if output_format == "JSON":
+                json_content = format_to_json(processed_data, sanitized_name)
+                json_path = save_output_file(
+                    json_content,
+                    f"{base_name}.json",
+                    output_dir
+                )
+                output_files.append((json_path, f"{base_name}.json"))
+
+            elif output_format == "Markdown":
+                md_content = format_to_markdown(processed_data)
+                md_path = save_output_file(
+                    md_content,
+                    f"{base_name}.md",
+                    output_dir
+                )
+                output_files.append((md_path, f"{base_name}.md"))
+
+            else:  # Ambos
+                json_content = format_to_json(processed_data, sanitized_name)
+                md_content = format_to_markdown(processed_data)
+
+                json_path = save_output_file(
+                    json_content,
+                    f"{base_name}.json",
+                    output_dir
+                )
+                md_path = save_output_file(
+                    md_content,
+                    f"{base_name}.md",
+                    output_dir
+                )
+
+                output_files.append((json_path, f"{base_name}.json"))
+                output_files.append((md_path, f"{base_name}.md"))
+
+            processed_count += 1
+            logger.info(f"Processado: {sanitized_name}")
+
+        except Exception as e:
+            logger.error(f"Erro ao processar {sanitized_name}: {e}")
+            logger.debug(traceback.format_exc())
+
+            # Continua com próximos arquivos
+            if total_files == 1:
+                raise gr.Error(
+                    f"❌ Erro ao processar {sanitized_name}: {str(e)}"
+                )
+
+    # Prepara saída final
+    if progress:
+        progress(0.9, desc="Preparando download...")
+
+    if not output_files:
+        raise gr.Error("❌ Nenhum arquivo foi processado com sucesso.")
+
+    # Se há múltiplos arquivos ou formato "Ambos", cria ZIP
+    if len(output_files) > 1 or output_format == "Ambos":
+        zip_path = create_zip_output(
+            output_files,
+            output_name="documentos_processados"
+        )
+        final_output = str(zip_path)
+    else:
+        final_output = str(output_files[0][0])
+
+    # Calcula tempo total
+    elapsed_time = time.time() - start_time
+
+    if progress:
+        progress(1.0, desc="Concluído!")
+
+    # Mensagem de status
+    status_msg = (
+        f"✅ Processamento concluído!\n\n"
+        f"📄 **Arquivos processados:** {processed_count}/{total_files}\n"
+        f"📦 **Formato:** {output_format}\n"
+        f"⏱️ **Tempo:** {elapsed_time:.1f} segundos"
+    )
+
+    logger.info(
+        f"Batch concluído: {processed_count}/{total_files} arquivos, "
+        f"{elapsed_time:.1f}s, formato={output_format}"
+    )
+
+    return final_output, status_msg
+
+
+# Versão com GPU (se disponível)
+if HAS_SPACES:
+    @spaces.GPU(duration=config.GPU_TIMEOUT_SECONDS)
+    def process_documents_gpu(
+        files: list,
+        output_format: str,
+        progress: gr.Progress = gr.Progress()
+    ) -> tuple[str | list[str], str]:
+        """Processamento com aceleração GPU via ZeroGPU."""
+        return _process_documents_internal(files, output_format, progress)
+else:
+    process_documents_gpu = None
+
+
+def process_documents(
+    files: list,
+    output_format: str,
+    request: gr.Request,
+    progress: gr.Progress = gr.Progress()
+) -> tuple[str | list[str], str]:
+    """
+    Função principal de processamento.
+
+    Usa GPU se disponível, senão fallback para CPU.
+
+    Args:
+        files: Lista de arquivos enviados.
+        output_format: Formato de saída.
+        request: Request do Gradio (para rate limiting).
+        progress: Objeto de progresso.
+
+    Returns:
+        Tupla (caminho do arquivo de saída, mensagem de status).
+    """
+    # Verifica rate limit
+    if not check_rate_limit(request):
+        raise gr.Error(
+            f"⚠️ Limite de requisições excedido. "
+            f"Máximo: {config.RATE_LIMIT_REQUESTS} por hora. "
+            f"Tente novamente mais tarde."
+        )
+
+    try:
+        # Tenta usar GPU
+        if HAS_SPACES and process_documents_gpu is not None:
+            logger.info("Usando processamento GPU (ZeroGPU)")
+            return process_documents_gpu(files, output_format, progress)
+        else:
+            logger.info("Usando processamento CPU (fallback)")
+            return _process_documents_internal(files, output_format, progress)
+
+    except gr.Error:
+        # Re-raise erros do Gradio
+        raise
+    except TimeoutError:
+        logger.error("Timeout no processamento")
+        raise gr.Error(
+            "⏱️ Tempo limite excedido. Tente com arquivos menores ou menos arquivos."
+        )
+    except MemoryError:
+        logger.error("Memória insuficiente")
+        raise gr.Error(
+            "💾 Memória insuficiente. Tente com arquivos menores."
+        )
+    except Exception as e:
+        logger.error(f"Erro inesperado: {e}")
+        logger.debug(traceback.format_exc())
+        raise gr.Error(f"❌ Erro inesperado: {str(e)}")
+
+
+# =============================================================================
+# INTERFACE GRADIO
+# =============================================================================
+
+# CSS customizado
+CUSTOM_CSS = """
+.main-container {
+    max-width: 900px;
+    margin: 0 auto;
+}
+
+.upload-box {
+    border: 2px dashed #4a90a4;
+    border-radius: 12px;
+    padding: 20px;
+    background: linear-gradient(135deg, #f8f9fa 0%, #e9ecef 100%);
+}
+
+.status-box {
+    background: #f0f7f4;
+    border-radius: 8px;
+    padding: 15px;
+    margin-top: 10px;
+}
+
+.info-text {
+    font-size: 0.9em;
+    color: #666;
+}
+"""
+
+# Texto de descrição
+DESCRIPTION = """
+# 📄 Docling Document Processor
+
+Converta documentos PDF, DOC e DOCX em formatos estruturados usando IA.
+
+## Recursos
+- 🔍 **Extração inteligente** de texto, tabelas e metadados
+-  **Detecção automática** de idioma
+- 🚀 **Aceleração GPU** para processamento rápido
+- 📊 **Preserva estrutura** hierárquica do documento
+"""
+
+INSTRUCTIONS = """
+### Como usar
+
+1. **Upload**: Arraste ou selecione seus arquivos (máx. 5 arquivos, 50MB cada)
+2. **Formato**: Escolha o formato de saída desejado
+3. **Processar**: Clique no botão e aguarde
+4. **Download**: Baixe o resultado quando concluído
+
+### Formatos suportados
+- **Entrada**: PDF, DOC, DOCX
+- **Saída**: JSON, Markdown ou ambos (ZIP)
+"""
+
+
+def create_interface() -> gr.Blocks:
+    """Cria e retorna a interface Gradio."""
+
+    with gr.Blocks(
+        title="Docling Document Processor",
+        theme=gr.themes.Soft(
+            primary_hue="teal",
+            secondary_hue="blue",
+        ),
+        css=CUSTOM_CSS,
+    ) as demo:
+
+        # Header
+        gr.Markdown(DESCRIPTION)
+
+        with gr.Row():
+            # Coluna principal
+            with gr.Column(scale=2):
+                # Upload de arquivos
+                file_input = gr.File(
+                    file_count="multiple",
+                    file_types=[".pdf", ".doc", ".docx"],
+                    label="📁 Upload de Documentos",
+                    elem_classes=["upload-box"],
+                )
+
+                # Seletor de formato
+                format_selector = gr.Radio(
+                    choices=config.OUTPUT_FORMATS,
+                    value="Markdown",
+                    label="📤 Formato de Saída",
+                    info="Escolha como deseja receber o documento processado",
+                )
+
+                # Botão de processar
+                process_btn = gr.Button(
+                    "🚀 Processar Documentos",
+                    variant="primary",
+                    size="lg",
+                )
+
+            # Coluna de informações
+            with gr.Column(scale=1):
+                gr.Markdown(INSTRUCTIONS)
+
+        # Área de resultados
+        with gr.Row():
+            with gr.Column():
+                # Status
+                status_output = gr.Markdown(
+                    label="Status",
+                    elem_classes=["status-box"],
+                )
+
+                # Arquivo de saída
+                file_output = gr.File(
+                    label="📥 Download do Resultado",
+                    interactive=False,
+                )
+
+        # Informações de limites
+        gr.Markdown(
+            f"""
+            ---
+            **Limites:** {config.MAX_FILES_PER_SESSION} arquivos por vez |
+            {config.MAX_FILE_SIZE_MB}MB por arquivo |
+            {config.RATE_LIMIT_REQUESTS} requisições/hora
+            """,
+            elem_classes=["info-text"],
+        )
+
+        # Evento de processamento
+        process_btn.click(
+            fn=process_documents,
+            inputs=[file_input, format_selector],
+            outputs=[file_output, status_output],
+            show_progress="full",
+        )
+
+        # Limpa status quando novos arquivos são selecionados
+        file_input.change(
+            fn=lambda: ("", None),
+            outputs=[status_output, file_output],
+        )
+
+    return demo
+
+
+# =============================================================================
+# PONTO DE ENTRADA
+# =============================================================================
+
+if __name__ == "__main__":
+    # Cria diretórios necessários
+    config.TEMP_DIR.mkdir(parents=True, exist_ok=True)
+    config.LOGS_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Limpa arquivos temporários antigos
+    cleanup_old_files()
+
+    logger.info("Iniciando Docling Document Processor...")
+    logger.info(f"ZeroGPU disponível: {HAS_SPACES}")
+
+    # Cria e lança a interface
+    demo = create_interface()
+
+    demo.queue().launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        max_file_size=f"{config.MAX_FILE_SIZE_MB}mb",
+        show_error=True,
+    )

config.py

@@ -0,0 +1,109 @@
+"""
+Configurações centralizadas para o Docling Document Processor.
+
+Este módulo contém todas as constantes e configurações usadas
+em toda a aplicação.
+"""
+
+from pathlib import Path
+
+# =============================================================================
+# LIMITES DE ARQUIVO
+# =============================================================================
+
+MAX_FILE_SIZE_MB: int = 50
+"""Tamanho máximo de arquivo em megabytes."""
+
+MAX_FILE_SIZE_BYTES: int = MAX_FILE_SIZE_MB * 1024 * 1024
+"""Tamanho máximo de arquivo em bytes (calculado)."""
+
+MAX_FILES_PER_SESSION: int = 5
+"""Número máximo de arquivos por upload."""
+
+# =============================================================================
+# PROCESSAMENTO
+# =============================================================================
+
+PROCESSING_TIMEOUT_SECONDS: int = 300
+"""Timeout para processamento de documentos (5 minutos)."""
+
+GPU_TIMEOUT_SECONDS: int = 300
+"""Timeout para execução GPU via ZeroGPU."""
+
+# =============================================================================
+# TIPOS DE ARQUIVO SUPORTADOS
+# =============================================================================
+
+SUPPORTED_EXTENSIONS: list[str] = [".pdf", ".doc", ".docx"]
+"""Extensões de arquivo aceitas."""
+
+SUPPORTED_MIME_TYPES: dict[str, list[str]] = {
+    ".pdf": ["application/pdf"],
+    ".doc": ["application/msword"],
+    ".docx": [
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+    ],
+}
+"""Mapeamento de extensões para MIME types válidos."""
+
+# =============================================================================
+# RATE LIMITING
+# =============================================================================
+
+RATE_LIMIT_REQUESTS: int = 10
+"""Número máximo de requisições por janela de tempo."""
+
+RATE_LIMIT_WINDOW_HOURS: int = 1
+"""Janela de tempo para rate limiting em horas."""
+
+# =============================================================================
+# DIRETÓRIOS
+# =============================================================================
+
+BASE_DIR: Path = Path(__file__).parent
+"""Diretório base da aplicação."""
+
+TEMP_DIR: Path = BASE_DIR / "temp"
+"""Diretório para arquivos temporários."""
+
+LOGS_DIR: Path = BASE_DIR / "logs"
+"""Diretório para arquivos de log."""
+
+TEMP_DIR_CLEANUP_HOURS: int = 1
+"""Tempo máximo de retenção de arquivos temporários em horas."""
+
+# =============================================================================
+# FORMATOS DE SAÍDA
+# =============================================================================
+
+OUTPUT_FORMATS: list[str] = ["JSON", "Markdown", "Ambos"]
+"""Formatos de saída disponíveis."""
+
+# =============================================================================
+# LOGGING
+# =============================================================================
+
+LOG_FILE: str = "docling_space.log"
+"""Nome do arquivo de log."""
+
+LOG_MAX_BYTES: int = 10 * 1024 * 1024  # 10MB
+"""Tamanho máximo do arquivo de log antes de rotacionar."""
+
+LOG_BACKUP_COUNT: int = 5
+"""Número de arquivos de backup de log a manter."""
+
+LOG_FORMAT: str = "[%(asctime)s] [%(levelname)s] [%(module)s] %(message)s"
+"""Formato das mensagens de log."""
+
+LOG_DATE_FORMAT: str = "%Y-%m-%d %H:%M:%S"
+"""Formato de data para logs."""
+
+# =============================================================================
+# CARACTERES PROIBIDOS EM NOMES DE ARQUIVO
+# =============================================================================
+
+FORBIDDEN_FILENAME_CHARS: str = r'<>:"/\|?*'
+"""Caracteres que devem ser removidos de nomes de arquivo."""
+
+FILENAME_MAX_LENGTH: int = 255
+"""Comprimento máximo de nome de arquivo."""

logs/.gitkeep

@@ -0,0 +1 @@
+# Este arquivo mantém o diretório logs no git

processors/__init__.py

@@ -0,0 +1,18 @@
+"""
+Módulo de processadores para o Docling Document Processor.
+
+Este pacote contém as classes e funções responsáveis pelo
+processamento de documentos e formatação de saída.
+"""
+
+from processors.docling_processor import DoclingProcessor
+from processors.json_formatter import format_to_json, JSONFormatter
+from processors.markdown_formatter import format_to_markdown, MarkdownFormatter
+
+__all__ = [
+    "DoclingProcessor",
+    "format_to_json",
+    "JSONFormatter",
+    "format_to_markdown",
+    "MarkdownFormatter",
+]

processors/docling_processor.py

@@ -0,0 +1,289 @@
+"""
+Processador principal usando Docling.
+
+Este módulo contém a classe DoclingProcessor que é responsável por
+converter documentos usando a biblioteca Docling.
+"""
+
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+from docling.document_converter import DocumentConverter
+from docling.datamodel.base_models import InputFormat
+from docling.datamodel.pipeline_options import (
+    PdfPipelineOptions,
+    TableFormerMode,
+)
+from docling.document_converter import PdfFormatOption
+
+from utils.logger import get_logger, ProcessingLogger
+
+# Logger para este módulo
+logger = get_logger(__name__)
+
+
+class DoclingProcessor:
+    """
+    Processador de documentos usando Docling.
+
+    Esta classe encapsula a lógica de conversão de documentos,
+    incluindo configuração de pipeline e extração de metadados.
+    """
+
+    def __init__(
+        self,
+        enable_ocr: bool = True,
+        enable_table_detection: bool = True,
+        use_gpu: bool = True
+    ):
+        """
+        Inicializa o processador Docling.
+
+        Args:
+            enable_ocr: Se deve habilitar OCR para imagens.
+            enable_table_detection: Se deve detectar tabelas.
+            use_gpu: Se deve tentar usar GPU para aceleração.
+        """
+        self.enable_ocr = enable_ocr
+        self.enable_table_detection = enable_table_detection
+        self.use_gpu = use_gpu
+
+        # Configuração do pipeline
+        self._setup_converter()
+
+        logger.info(
+            f"DoclingProcessor inicializado "
+            f"(OCR={enable_ocr}, tabelas={enable_table_detection}, GPU={use_gpu})"
+        )
+
+    def _setup_converter(self) -> None:
+        """Configura o DocumentConverter com as opções adequadas."""
+        # Configurações específicas para PDF
+        pipeline_options = PdfPipelineOptions()
+        pipeline_options.do_ocr = self.enable_ocr
+        pipeline_options.do_table_structure = self.enable_table_detection
+
+        if self.enable_table_detection:
+            # Usa TableFormer para melhor detecção de tabelas
+            pipeline_options.table_structure_options.mode = TableFormerMode.ACCURATE
+
+        # Cria o converter com as opções
+        self.converter = DocumentConverter(
+            format_options={
+                InputFormat.PDF: PdfFormatOption(
+                    pipeline_options=pipeline_options
+                )
+            }
+        )
+
+    def process_document(self, file_path: str | Path) -> dict[str, Any]:
+        """
+        Processa um documento e retorna dados estruturados.
+
+        Args:
+            file_path: Caminho para o arquivo a processar.
+
+        Returns:
+            Dicionário com documento convertido, metadados e tabelas.
+
+        Raises:
+            Exception: Se o processamento falhar.
+        """
+        file_path = Path(file_path)
+
+        with ProcessingLogger(logger, "Conversão Docling", file_path.name):
+            start_time = time.time()
+
+            try:
+                # Converte o documento
+                result = self.converter.convert(str(file_path))
+
+                # Extrai informações
+                document = result.document
+
+                processing_time = time.time() - start_time
+
+                return {
+                    "document": document,
+                    "metadata": self._extract_metadata(result, file_path),
+                    "tables": self._extract_tables(document),
+                    "language": self._detect_language(document),
+                    "processing_time_seconds": processing_time,
+                }
+
+            except Exception as e:
+                logger.error(f"Erro ao processar {file_path.name}: {e}")
+                raise
+
+    def _extract_metadata(
+        self,
+        result: Any,
+        file_path: Path
+    ) -> dict[str, Any]:
+        """
+        Extrai metadados do documento processado.
+
+        Args:
+            result: Resultado da conversão Docling.
+            file_path: Caminho do arquivo original.
+
+        Returns:
+            Dicionário com metadados do documento.
+        """
+        document = result.document
+
+        metadata = {
+            "nome_arquivo": file_path.name,
+            "extensao": file_path.suffix.lower(),
+            "tamanho_bytes": file_path.stat().st_size if file_path.exists() else 0,
+        }
+
+        # Tenta extrair metadados do documento
+        try:
+            if hasattr(document, "metadata") and document.metadata:
+                doc_meta = document.metadata
+                if hasattr(doc_meta, "title") and doc_meta.title:
+                    metadata["titulo"] = doc_meta.title
+                if hasattr(doc_meta, "author") and doc_meta.author:
+                    metadata["autor"] = doc_meta.author
+                if hasattr(doc_meta, "creation_date") and doc_meta.creation_date:
+                    metadata["data_criacao"] = str(doc_meta.creation_date)
+        except Exception as e:
+            logger.debug(f"Não foi possível extrair metadados: {e}")
+
+        # Contagem de elementos
+        try:
+            if hasattr(document, "pages"):
+                metadata["num_paginas"] = len(list(document.pages))
+            if hasattr(document, "tables"):
+                metadata["num_tabelas"] = len(list(document.tables))
+            if hasattr(document, "pictures"):
+                metadata["num_imagens"] = len(list(document.pictures))
+        except Exception as e:
+            logger.debug(f"Erro ao contar elementos: {e}")
+
+        return metadata
+
+    def _extract_tables(self, document: Any) -> list[dict[str, Any]]:
+        """
+        Extrai tabelas do documento.
+
+        Args:
+            document: Documento Docling convertido.
+
+        Returns:
+            Lista de dicionários representando tabelas.
+        """
+        tables = []
+
+        try:
+            if not hasattr(document, "tables"):
+                return tables
+
+            for i, table in enumerate(document.tables):
+                table_data = {
+                    "indice": i + 1,
+                    "dados": None,
+                    "linhas": 0,
+                    "colunas": 0,
+                }
+
+                # Tenta extrair dados da tabela
+                try:
+                    if hasattr(table, "export_to_dataframe"):
+                        df = table.export_to_dataframe()
+                        table_data["dados"] = df.to_dict(orient="records")
+                        table_data["linhas"] = len(df)
+                        table_data["colunas"] = len(df.columns)
+                        table_data["colunas_nomes"] = list(df.columns)
+                    elif hasattr(table, "to_markdown"):
+                        table_data["markdown"] = table.to_markdown()
+                except Exception as e:
+                    logger.debug(f"Erro ao exportar tabela {i+1}: {e}")
+                    # Fallback: tenta obter texto
+                    if hasattr(table, "text"):
+                        table_data["texto"] = table.text
+
+                tables.append(table_data)
+
+        except Exception as e:
+            logger.warning(f"Erro ao extrair tabelas: {e}")
+
+        logger.debug(f"Extraídas {len(tables)} tabelas")
+        return tables
+
+    def _detect_language(self, document: Any) -> str:
+        """
+        Detecta o idioma do documento.
+
+        Args:
+            document: Documento Docling convertido.
+
+        Returns:
+            Código do idioma detectado (ex: "pt", "en").
+        """
+        try:
+            # Tenta usar langdetect
+            from langdetect import detect, LangDetectException
+
+            # Extrai texto do documento
+            if hasattr(document, "export_to_text"):
+                text = document.export_to_text()
+            elif hasattr(document, "export_to_markdown"):
+                text = document.export_to_markdown()
+            else:
+                return "desconhecido"
+
+            # Usa apenas os primeiros 1000 caracteres para detecção
+            sample = text[:1000] if text else ""
+
+            if len(sample) < 20:
+                return "desconhecido"
+
+            lang = detect(sample)
+            logger.debug(f"Idioma detectado: {lang}")
+            return lang
+
+        except LangDetectException:
+            return "desconhecido"
+        except ImportError:
+            logger.warning("langdetect não disponível")
+            return "nao_detectado"
+        except Exception as e:
+            logger.debug(f"Erro na detecção de idioma: {e}")
+            return "erro"
+
+    def get_markdown(self, processed_data: dict[str, Any]) -> str:
+        """
+        Obtém o documento em formato Markdown.
+
+        Args:
+            processed_data: Dados retornados por process_document().
+
+        Returns:
+            String com o documento em Markdown.
+        """
+        document = processed_data.get("document")
+
+        if document and hasattr(document, "export_to_markdown"):
+            return document.export_to_markdown()
+
+        return ""
+
+    def get_text(self, processed_data: dict[str, Any]) -> str:
+        """
+        Obtém o documento em texto puro.
+
+        Args:
+            processed_data: Dados retornados por process_document().
+
+        Returns:
+            String com o texto do documento.
+        """
+        document = processed_data.get("document")
+
+        if document and hasattr(document, "export_to_text"):
+            return document.export_to_text()
+
+        return ""

processors/json_formatter.py

@@ -0,0 +1,226 @@
+"""
+Formatador de saída JSON.
+
+Este módulo contém funções e classes para formatar documentos
+processados em formato JSON estruturado.
+"""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from utils.logger import get_logger
+
+# Logger para este módulo
+logger = get_logger(__name__)
+
+
+def format_to_json(
+    processed_data: dict[str, Any],
+    filename: str,
+    include_raw_content: bool = True,
+    pretty_print: bool = True
+) -> str:
+    """
+    Formata dados processados em JSON estruturado.
+
+    Args:
+        processed_data: Dados retornados pelo DoclingProcessor.
+        filename: Nome do arquivo original.
+        include_raw_content: Se deve incluir conteúdo completo.
+        pretty_print: Se deve formatar com indentação.
+
+    Returns:
+        String JSON formatada.
+    """
+    document = processed_data.get("document")
+    metadata = processed_data.get("metadata", {})
+    tables = processed_data.get("tables", [])
+    language = processed_data.get("language", "desconhecido")
+
+    # Estrutura de saída
+    output = {
+        "arquivo": filename,
+        "idioma": language,
+        "processado_em": datetime.now().isoformat(),
+        "metadados": metadata,
+        "tabelas": tables,
+    }
+
+    # Adiciona conteúdo
+    if include_raw_content and document:
+        try:
+            # Tenta exportar para dict
+            if hasattr(document, "export_to_dict"):
+                output["conteudo"] = document.export_to_dict()
+            elif hasattr(document, "export_to_markdown"):
+                output["conteudo_markdown"] = document.export_to_markdown()
+            elif hasattr(document, "export_to_text"):
+                output["conteudo_texto"] = document.export_to_text()
+        except Exception as e:
+            logger.warning(f"Erro ao exportar conteúdo: {e}")
+            output["conteudo"] = None
+            output["erro_exportacao"] = str(e)
+
+    # Adiciona tempo de processamento se disponível
+    if "processing_time_seconds" in processed_data:
+        output["tempo_processamento_segundos"] = processed_data["processing_time_seconds"]
+
+    # Serializa para JSON
+    indent = 2 if pretty_print else None
+
+    try:
+        return json.dumps(
+            output,
+            ensure_ascii=False,
+            indent=indent,
+            default=_json_serializer
+        )
+    except Exception as e:
+        logger.error(f"Erro ao serializar JSON: {e}")
+        # Fallback: tenta sem conteúdo complexo
+        output.pop("conteudo", None)
+        output["erro_serializacao"] = str(e)
+        return json.dumps(output, ensure_ascii=False, indent=indent)
+
+
+def _json_serializer(obj: Any) -> Any:
+    """
+    Serializador customizado para objetos não-JSON.
+
+    Args:
+        obj: Objeto a serializar.
+
+    Returns:
+        Representação serializável do objeto.
+    """
+    if hasattr(obj, "isoformat"):
+        return obj.isoformat()
+    if hasattr(obj, "__dict__"):
+        return obj.__dict__
+    if isinstance(obj, bytes):
+        return obj.decode("utf-8", errors="replace")
+    if isinstance(obj, set):
+        return list(obj)
+    if isinstance(obj, Path):
+        return str(obj)
+
+    return str(obj)
+
+
+class JSONFormatter:
+    """
+    Classe para formatação JSON com configurações personalizadas.
+
+    Permite manter configurações consistentes entre múltiplas formatações.
+    """
+
+    def __init__(
+        self,
+        include_raw_content: bool = True,
+        pretty_print: bool = True,
+        include_tables: bool = True,
+        include_metadata: bool = True
+    ):
+        """
+        Inicializa o formatador JSON.
+
+        Args:
+            include_raw_content: Se deve incluir conteúdo completo.
+            pretty_print: Se deve formatar com indentação.
+            include_tables: Se deve incluir tabelas extraídas.
+            include_metadata: Se deve incluir metadados.
+        """
+        self.include_raw_content = include_raw_content
+        self.pretty_print = pretty_print
+        self.include_tables = include_tables
+        self.include_metadata = include_metadata
+
+    def format(
+        self,
+        processed_data: dict[str, Any],
+        filename: str
+    ) -> str:
+        """
+        Formata dados processados em JSON.
+
+        Args:
+            processed_data: Dados do DoclingProcessor.
+            filename: Nome do arquivo original.
+
+        Returns:
+            String JSON formatada.
+        """
+        # Copia para não modificar original
+        data = processed_data.copy()
+
+        # Remove elementos não desejados
+        if not self.include_tables:
+            data["tables"] = []
+
+        if not self.include_metadata:
+            data["metadata"] = {}
+
+        return format_to_json(
+            data,
+            filename,
+            include_raw_content=self.include_raw_content,
+            pretty_print=self.pretty_print
+        )
+
+    def format_batch(
+        self,
+        items: list[tuple[dict[str, Any], str]]
+    ) -> str:
+        """
+        Formata múltiplos documentos em um único JSON.
+
+        Args:
+            items: Lista de tuplas (processed_data, filename).
+
+        Returns:
+            String JSON com array de documentos.
+        """
+        documents = []
+
+        for processed_data, filename in items:
+            # Formata individualmente e converte de volta para dict
+            json_str = self.format(processed_data, filename)
+            doc = json.loads(json_str)
+            documents.append(doc)
+
+        indent = 2 if self.pretty_print else None
+
+        return json.dumps(
+            {"documentos": documents, "total": len(documents)},
+            ensure_ascii=False,
+            indent=indent
+        )
+
+
+def save_json(
+    content: str | dict,
+    output_path: str | Path,
+    encoding: str = "utf-8"
+) -> Path:
+    """
+    Salva conteúdo JSON em arquivo.
+
+    Args:
+        content: String JSON ou dicionário.
+        output_path: Caminho do arquivo de saída.
+        encoding: Encoding do arquivo.
+
+    Returns:
+        Path para o arquivo salvo.
+    """
+    output_path = Path(output_path)
+
+    if isinstance(content, dict):
+        content = json.dumps(content, ensure_ascii=False, indent=2)
+
+    output_path.write_text(content, encoding=encoding)
+    logger.debug(f"JSON salvo: {output_path}")
+
+    return output_path

processors/markdown_formatter.py

@@ -0,0 +1,333 @@
+"""
+Formatador de saída Markdown.
+
+Este módulo contém funções e classes para formatar documentos
+processados em formato Markdown.
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Optional
+
+from utils.logger import get_logger
+
+# Logger para este módulo
+logger = get_logger(__name__)
+
+
+def format_to_markdown(
+    processed_data: dict[str, Any],
+    include_metadata_header: bool = True,
+    include_tables: bool = True
+) -> str:
+    """
+    Formata dados processados em Markdown.
+
+    Args:
+        processed_data: Dados retornados pelo DoclingProcessor.
+        include_metadata_header: Se deve incluir cabeçalho com metadados.
+        include_tables: Se deve incluir tabelas formatadas.
+
+    Returns:
+        String Markdown formatada.
+    """
+    document = processed_data.get("document")
+    metadata = processed_data.get("metadata", {})
+    tables = processed_data.get("tables", [])
+    language = processed_data.get("language", "desconhecido")
+
+    sections = []
+
+    # Cabeçalho com metadados
+    if include_metadata_header:
+        header = _format_metadata_header(metadata, language)
+        if header:
+            sections.append(header)
+
+    # Conteúdo principal do documento
+    if document:
+        try:
+            if hasattr(document, "export_to_markdown"):
+                content = document.export_to_markdown()
+                if content:
+                    sections.append(content)
+        except Exception as e:
+            logger.warning(f"Erro ao exportar Markdown: {e}")
+            sections.append(f"> ⚠️ Erro ao exportar conteúdo: {e}")
+
+    # Tabelas (se não foram incluídas no export padrão)
+    if include_tables and tables:
+        tables_section = _format_tables_section(tables)
+        if tables_section:
+            sections.append(tables_section)
+
+    return "\n\n---\n\n".join(sections)
+
+
+def _format_metadata_header(
+    metadata: dict[str, Any],
+    language: str
+) -> str:
+    """
+    Formata cabeçalho com metadados.
+
+    Args:
+        metadata: Dicionário de metadados.
+        language: Código do idioma.
+
+    Returns:
+        String Markdown com metadados.
+    """
+    lines = []
+
+    # Título
+    titulo = metadata.get("titulo", metadata.get("nome_arquivo", "Documento"))
+    lines.append(f"# {titulo}")
+    lines.append("")
+
+    # Metadados como lista
+    meta_items = []
+
+    if metadata.get("autor"):
+        meta_items.append(f"**Autor:** {metadata['autor']}")
+
+    if metadata.get("data_criacao"):
+        meta_items.append(f"**Data de criação:** {metadata['data_criacao']}")
+
+    if language and language not in ("desconhecido", "erro", "nao_detectado"):
+        lang_names = {
+            "pt": "Português",
+            "en": "Inglês",
+            "es": "Espanhol",
+            "fr": "Francês",
+            "de": "Alemão",
+            "it": "Italiano",
+        }
+        lang_name = lang_names.get(language, language.upper())
+        meta_items.append(f"**Idioma:** {lang_name}")
+
+    if metadata.get("num_paginas"):
+        meta_items.append(f"**Páginas:** {metadata['num_paginas']}")
+
+    if metadata.get("num_tabelas"):
+        meta_items.append(f"**Tabelas:** {metadata['num_tabelas']}")
+
+    if metadata.get("num_imagens"):
+        meta_items.append(f"**Imagens:** {metadata['num_imagens']}")
+
+    if meta_items:
+        lines.extend(meta_items)
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _format_tables_section(tables: list[dict[str, Any]]) -> str:
+    """
+    Formata seção de tabelas.
+
+    Args:
+        tables: Lista de tabelas extraídas.
+
+    Returns:
+        String Markdown com tabelas.
+    """
+    if not tables:
+        return ""
+
+    lines = ["## Tabelas Extraídas", ""]
+
+    for table in tables:
+        index = table.get("indice", 0)
+        lines.append(f"### Tabela {index}")
+        lines.append("")
+
+        # Se tem dados como dict/list, formata como tabela MD
+        if table.get("dados"):
+            md_table = _dict_to_markdown_table(table["dados"])
+            lines.append(md_table)
+        elif table.get("markdown"):
+            lines.append(table["markdown"])
+        elif table.get("texto"):
+            lines.append(f"```\n{table['texto']}\n```")
+        else:
+            lines.append("*Dados da tabela não disponíveis*")
+
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _dict_to_markdown_table(data: list[dict[str, Any]]) -> str:
+    """
+    Converte lista de dicionários em tabela Markdown.
+
+    Args:
+        data: Lista de dicionários (cada dict = uma linha).
+
+    Returns:
+        String com tabela em formato Markdown pipe.
+    """
+    if not data:
+        return "*Tabela vazia*"
+
+    # Pega colunas do primeiro item
+    headers = list(data[0].keys())
+
+    lines = []
+
+    # Cabeçalho
+    header_line = "| " + " | ".join(str(h) for h in headers) + " |"
+    lines.append(header_line)
+
+    # Separador
+    separator = "| " + " | ".join("---" for _ in headers) + " |"
+    lines.append(separator)
+
+    # Dados
+    for row in data:
+        values = []
+        for h in headers:
+            value = row.get(h, "")
+            # Escapa pipes no conteúdo
+            value = str(value).replace("|", "\\|")
+            # Remove quebras de linha
+            value = value.replace("\n", " ")
+            values.append(value)
+
+        row_line = "| " + " | ".join(values) + " |"
+        lines.append(row_line)
+
+    return "\n".join(lines)
+
+
+class MarkdownFormatter:
+    """
+    Classe para formatação Markdown com configurações personalizadas.
+
+    Permite manter configurações consistentes entre múltiplas formatações.
+    """
+
+    def __init__(
+        self,
+        include_metadata_header: bool = True,
+        include_tables: bool = True,
+        include_toc: bool = False,
+        max_heading_level: int = 6
+    ):
+        """
+        Inicializa o formatador Markdown.
+
+        Args:
+            include_metadata_header: Se deve incluir cabeçalho com metadados.
+            include_tables: Se deve incluir tabelas extraídas.
+            include_toc: Se deve incluir sumário (Table of Contents).
+            max_heading_level: Nível máximo de heading a usar.
+        """
+        self.include_metadata_header = include_metadata_header
+        self.include_tables = include_tables
+        self.include_toc = include_toc
+        self.max_heading_level = max_heading_level
+
+    def format(self, processed_data: dict[str, Any]) -> str:
+        """
+        Formata dados processados em Markdown.
+
+        Args:
+            processed_data: Dados do DoclingProcessor.
+
+        Returns:
+            String Markdown formatada.
+        """
+        content = format_to_markdown(
+            processed_data,
+            include_metadata_header=self.include_metadata_header,
+            include_tables=self.include_tables
+        )
+
+        if self.include_toc:
+            toc = self._generate_toc(content)
+            if toc:
+                content = f"{toc}\n\n---\n\n{content}"
+
+        return content
+
+    def _generate_toc(self, content: str) -> str:
+        """
+        Gera sumário (Table of Contents) do conteúdo.
+
+        Args:
+            content: Conteúdo Markdown.
+
+        Returns:
+            String com sumário em Markdown.
+        """
+        import re
+
+        lines = []
+        lines.append("## Sumário")
+        lines.append("")
+
+        # Encontra headings
+        heading_pattern = r"^(#{1,6})\s+(.+)$"
+
+        for line in content.split("\n"):
+            match = re.match(heading_pattern, line)
+            if match:
+                level = len(match.group(1))
+                title = match.group(2)
+
+                if level <= self.max_heading_level:
+                    # Cria link
+                    anchor = self._slugify(title)
+                    indent = "  " * (level - 1)
+                    lines.append(f"{indent}- [{title}](#{anchor})")
+
+        return "\n".join(lines) if len(lines) > 2 else ""
+
+    def _slugify(self, text: str) -> str:
+        """
+        Converte texto em slug para anchor.
+
+        Args:
+            text: Texto a converter.
+
+        Returns:
+            Slug do texto.
+        """
+        import re
+
+        # Converte para lowercase
+        slug = text.lower()
+
+        # Remove caracteres especiais
+        slug = re.sub(r"[^\w\s-]", "", slug)
+
+        # Substitui espaços por hífens
+        slug = re.sub(r"\s+", "-", slug)
+
+        return slug
+
+
+def save_markdown(
+    content: str,
+    output_path: str | Path,
+    encoding: str = "utf-8"
+) -> Path:
+    """
+    Salva conteúdo Markdown em arquivo.
+
+    Args:
+        content: String Markdown.
+        output_path: Caminho do arquivo de saída.
+        encoding: Encoding do arquivo.
+
+    Returns:
+        Path para o arquivo salvo.
+    """
+    output_path = Path(output_path)
+
+    output_path.write_text(content, encoding=encoding)
+    logger.debug(f"Markdown salvo: {output_path}")
+
+    return output_path

requirements.txt

@@ -0,0 +1,26 @@
+# =============================================================================
+# Docling Document Processor - Dependências
+# =============================================================================
+
+# Framework de interface web
+gradio>=4.44.0
+
+# Processamento de documentos
+docling>=2.31.0
+
+# Hugging Face
+huggingface-hub>=0.24.0
+spaces>=0.34.0
+
+# Manipulação de arquivos
+python-docx>=1.1.0
+PyPDF2>=3.0.0
+
+# Validação de MIME types
+python-magic>=0.4.27
+
+# Detecção de idioma
+langdetect>=1.0.9
+
+# Utilitários
+tqdm>=4.66.0

tests/__init__.py

@@ -0,0 +1,3 @@
+"""
+Módulo de testes para o Docling Document Processor.
+"""

tests/test_processors.py

@@ -0,0 +1,403 @@
+"""
+Testes unitários para os processadores e validadores.
+
+Execute com: python -m pytest tests/test_processors.py -v
+"""
+
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# Adiciona o diretório pai ao path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import config
+from utils.validators import (
+    ValidationError,
+    sanitize_filename,
+    validate_file_count,
+    validate_file_size,
+)
+
+
+# =============================================================================
+# FIXTURES
+# =============================================================================
+
+@pytest.fixture
+def temp_file():
+    """Cria um arquivo temporário para testes."""
+    with tempfile.NamedTemporaryFile(
+        mode="wb",
+        suffix=".pdf",
+        delete=False
+    ) as f:
+        # Escreve conteúdo mínimo de PDF
+        f.write(b"%PDF-1.4\n")
+        f.write(b"1 0 obj\n<< /Type /Catalog >>\nendobj\n")
+        f.write(b"%%EOF\n")
+        temp_path = f.name
+
+    yield temp_path
+
+    # Cleanup
+    if os.path.exists(temp_path):
+        os.unlink(temp_path)
+
+
+@pytest.fixture
+def large_temp_file():
+    """Cria um arquivo temporário grande (> limite)."""
+    with tempfile.NamedTemporaryFile(
+        mode="wb",
+        suffix=".pdf",
+        delete=False
+    ) as f:
+        # Escreve mais que o limite
+        f.write(b"X" * (config.MAX_FILE_SIZE_BYTES + 1000))
+        temp_path = f.name
+
+    yield temp_path
+
+    if os.path.exists(temp_path):
+        os.unlink(temp_path)
+
+
+@pytest.fixture
+def empty_temp_file():
+    """Cria um arquivo temporário vazio."""
+    with tempfile.NamedTemporaryFile(
+        mode="wb",
+        suffix=".pdf",
+        delete=False
+    ) as f:
+        temp_path = f.name
+
+    yield temp_path
+
+    if os.path.exists(temp_path):
+        os.unlink(temp_path)
+
+
+# =============================================================================
+# TESTES DE VALIDAÇÃO
+# =============================================================================
+
+class TestValidateFileCount:
+    """Testes para validate_file_count()."""
+
+    def test_valid_count_single(self):
+        """Teste com um arquivo."""
+        assert validate_file_count([1]) is True
+
+    def test_valid_count_multiple(self):
+        """Teste com múltiplos arquivos dentro do limite."""
+        files = list(range(config.MAX_FILES_PER_SESSION))
+        assert validate_file_count(files) is True
+
+    def test_empty_list_raises(self):
+        """Teste com lista vazia deve falhar."""
+        with pytest.raises(ValidationError) as exc_info:
+            validate_file_count([])
+
+        assert exc_info.value.error_code == "NO_FILES"
+
+    def test_too_many_files_raises(self):
+        """Teste com arquivos demais deve falhar."""
+        files = list(range(config.MAX_FILES_PER_SESSION + 1))
+
+        with pytest.raises(ValidationError) as exc_info:
+            validate_file_count(files)
+
+        assert exc_info.value.error_code == "TOO_MANY_FILES"
+
+
+class TestValidateFileSize:
+    """Testes para validate_file_size()."""
+
+    def test_valid_size(self, temp_file):
+        """Teste com arquivo de tamanho válido."""
+        assert validate_file_size(temp_file) is True
+
+    def test_file_too_large(self, large_temp_file):
+        """Teste com arquivo muito grande."""
+        with pytest.raises(ValidationError) as exc_info:
+            validate_file_size(large_temp_file)
+
+        assert exc_info.value.error_code == "FILE_TOO_LARGE"
+
+    def test_empty_file(self, empty_temp_file):
+        """Teste com arquivo vazio."""
+        with pytest.raises(ValidationError) as exc_info:
+            validate_file_size(empty_temp_file)
+
+        assert exc_info.value.error_code == "EMPTY_FILE"
+
+    def test_file_not_found(self):
+        """Teste com arquivo inexistente."""
+        with pytest.raises(ValidationError) as exc_info:
+            validate_file_size("/caminho/inexistente/arquivo.pdf")
+
+        assert exc_info.value.error_code == "FILE_NOT_FOUND"
+
+
+class TestSanitizeFilename:
+    """Testes para sanitize_filename()."""
+
+    def test_normal_filename(self):
+        """Teste com nome normal."""
+        assert sanitize_filename("documento.pdf") == "documento.pdf"
+
+    def test_special_characters(self):
+        """Teste com caracteres especiais."""
+        result = sanitize_filename("doc<>:test.pdf")
+        assert "<" not in result
+        assert ">" not in result
+        assert ":" not in result
+
+    def test_spaces(self):
+        """Teste com espaços."""
+        result = sanitize_filename("meu documento.pdf")
+        assert result == "meu_documento.pdf"
+
+    def test_multiple_underscores(self):
+        """Teste com underscores múltiplos."""
+        result = sanitize_filename("doc___test.pdf")
+        assert "___" not in result
+
+    def test_empty_filename(self):
+        """Teste com nome vazio."""
+        result = sanitize_filename("")
+        assert result == "arquivo_sem_nome"
+
+    def test_long_filename(self):
+        """Teste com nome muito longo."""
+        long_name = "a" * 300 + ".pdf"
+        result = sanitize_filename(long_name)
+        assert len(result) <= config.FILENAME_MAX_LENGTH
+
+
+# =============================================================================
+# TESTES DE FORMATAÇÃO JSON
+# =============================================================================
+
+class TestJSONFormatter:
+    """Testes para json_formatter.py."""
+
+    def test_format_to_json_basic(self):
+        """Teste de formatação JSON básica."""
+        from processors.json_formatter import format_to_json
+
+        # Mock de dados processados
+        mock_document = MagicMock()
+        mock_document.export_to_dict.return_value = {"content": "teste"}
+
+        processed_data = {
+            "document": mock_document,
+            "metadata": {"nome_arquivo": "test.pdf"},
+            "tables": [],
+            "language": "pt",
+        }
+
+        result = format_to_json(processed_data, "test.pdf")
+
+        assert isinstance(result, str)
+
+        parsed = json.loads(result)
+        assert parsed["arquivo"] == "test.pdf"
+        assert parsed["idioma"] == "pt"
+        assert "processado_em" in parsed
+
+    def test_format_to_json_with_tables(self):
+        """Teste de formatação JSON com tabelas."""
+        from processors.json_formatter import format_to_json
+
+        mock_document = MagicMock()
+        mock_document.export_to_dict.return_value = {}
+
+        processed_data = {
+            "document": mock_document,
+            "metadata": {},
+            "tables": [
+                {"indice": 1, "dados": [{"col1": "val1"}]}
+            ],
+            "language": "en",
+        }
+
+        result = format_to_json(processed_data, "test.pdf")
+        parsed = json.loads(result)
+
+        assert len(parsed["tabelas"]) == 1
+        assert parsed["tabelas"][0]["indice"] == 1
+
+
+# =============================================================================
+# TESTES DE FORMATAÇÃO MARKDOWN
+# =============================================================================
+
+class TestMarkdownFormatter:
+    """Testes para markdown_formatter.py."""
+
+    def test_format_to_markdown_basic(self):
+        """Teste de formatação Markdown básica."""
+        from processors.markdown_formatter import format_to_markdown
+
+        mock_document = MagicMock()
+        mock_document.export_to_markdown.return_value = "# Conteúdo\n\nTexto aqui."
+
+        processed_data = {
+            "document": mock_document,
+            "metadata": {"nome_arquivo": "test.pdf", "num_paginas": 3},
+            "tables": [],
+            "language": "pt",
+        }
+
+        result = format_to_markdown(processed_data)
+
+        assert isinstance(result, str)
+        assert "# " in result or "## " in result  # Tem headings
+
+    def test_dict_to_markdown_table(self):
+        """Teste de conversão de dict para tabela MD."""
+        from processors.markdown_formatter import _dict_to_markdown_table
+
+        data = [
+            {"Nome": "Alice", "Idade": 30},
+            {"Nome": "Bob", "Idade": 25},
+        ]
+
+        result = _dict_to_markdown_table(data)
+
+        assert "| Nome | Idade |" in result
+        assert "| --- | --- |" in result
+        assert "| Alice | 30 |" in result
+        assert "| Bob | 25 |" in result
+
+    def test_empty_table(self):
+        """Teste com tabela vazia."""
+        from processors.markdown_formatter import _dict_to_markdown_table
+
+        result = _dict_to_markdown_table([])
+        assert "vazia" in result.lower()
+
+
+# =============================================================================
+# TESTES DE FILE HANDLER
+# =============================================================================
+
+class TestFileHandler:
+    """Testes para file_handler.py."""
+
+    def test_create_temp_directory(self):
+        """Teste de criação de diretório temporário."""
+        from utils.file_handler import create_temp_directory
+
+        temp_dir = create_temp_directory(prefix="test_")
+
+        try:
+            assert temp_dir.exists()
+            assert temp_dir.is_dir()
+            assert "test_" in temp_dir.name
+        finally:
+            # Cleanup
+            if temp_dir.exists():
+                import shutil
+                shutil.rmtree(temp_dir)
+
+    def test_save_output_file(self):
+        """Teste de salvamento de arquivo de saída."""
+        from utils.file_handler import save_output_file, create_temp_directory
+
+        temp_dir = create_temp_directory(prefix="test_")
+
+        try:
+            content = "Conteúdo de teste"
+            output_path = save_output_file(content, "teste.txt", temp_dir)
+
+            assert output_path.exists()
+            assert output_path.read_text() == content
+        finally:
+            import shutil
+            if temp_dir.exists():
+                shutil.rmtree(temp_dir)
+
+    def test_format_size(self):
+        """Teste de formatação de tamanho."""
+        from utils.file_handler import format_size
+
+        assert "B" in format_size(500)
+        assert "KB" in format_size(1024 * 5)
+        assert "MB" in format_size(1024 * 1024 * 10)
+        assert "GB" in format_size(1024 * 1024 * 1024 * 2)
+
+
+# =============================================================================
+# TESTES DE INTEGRAÇÃO (MOCK)
+# =============================================================================
+
+class TestDoclingProcessorMock:
+    """Testes do DoclingProcessor com mocks."""
+
+    @patch("processors.docling_processor.DocumentConverter")
+    def test_processor_initialization(self, mock_converter_class):
+        """Teste de inicialização do processador."""
+        from processors.docling_processor import DoclingProcessor
+
+        processor = DoclingProcessor(
+            enable_ocr=True,
+            enable_table_detection=True,
+            use_gpu=False
+        )
+
+        assert processor.enable_ocr is True
+        assert processor.enable_table_detection is True
+        assert processor.use_gpu is False
+
+    @patch("processors.docling_processor.DocumentConverter")
+    def test_processor_process_document(self, mock_converter_class):
+        """Teste de processamento de documento."""
+        from processors.docling_processor import DoclingProcessor
+
+        # Setup mock
+        mock_converter = MagicMock()
+        mock_converter_class.return_value = mock_converter
+
+        mock_result = MagicMock()
+        mock_document = MagicMock()
+        mock_document.export_to_markdown.return_value = "# Teste"
+        mock_result.document = mock_document
+
+        mock_converter.convert.return_value = mock_result
+
+        # Cria arquivo temporário
+        with tempfile.NamedTemporaryFile(
+            mode="wb",
+            suffix=".pdf",
+            delete=False
+        ) as f:
+            f.write(b"%PDF-1.4\n%%EOF\n")
+            temp_path = f.name
+
+        try:
+            processor = DoclingProcessor()
+            result = processor.process_document(temp_path)
+
+            assert "document" in result
+            assert "metadata" in result
+            assert "tables" in result
+            assert "language" in result
+        finally:
+            os.unlink(temp_path)
+
+
+# =============================================================================
+# EXECUTAR TESTES
+# =============================================================================
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

utils/__init__.py

@@ -0,0 +1,38 @@
+"""
+Módulo de utilitários para o Docling Document Processor.
+
+Este pacote contém funções auxiliares para validação, manipulação
+de arquivos e logging.
+"""
+
+from utils.validators import (
+    validate_file_count,
+    validate_file_size,
+    validate_mime_type,
+    sanitize_filename,
+    ValidationError,
+)
+from utils.file_handler import (
+    create_temp_directory,
+    cleanup_old_files,
+    create_zip_output,
+    get_temp_file_path,
+)
+from utils.logger import setup_logger, get_logger
+
+__all__ = [
+    # Validators
+    "validate_file_count",
+    "validate_file_size",
+    "validate_mime_type",
+    "sanitize_filename",
+    "ValidationError",
+    # File handler
+    "create_temp_directory",
+    "cleanup_old_files",
+    "create_zip_output",
+    "get_temp_file_path",
+    # Logger
+    "setup_logger",
+    "get_logger",
+]

utils/file_handler.py

@@ -0,0 +1,257 @@
+"""
+Manipulação de arquivos temporários e outputs.
+
+Este módulo contém funções para gerenciar arquivos temporários,
+criar outputs em diferentes formatos e limpar arquivos antigos.
+"""
+
+import os
+import shutil
+import tempfile
+import time
+import zipfile
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+import config
+from utils.logger import get_logger
+
+# Logger para este módulo
+logger = get_logger(__name__)
+
+
+def create_temp_directory(prefix: str = "docling_") -> Path:
+    """
+    Cria um diretório temporário isolado para processamento.
+
+    Args:
+        prefix: Prefixo para o nome do diretório.
+
+    Returns:
+        Path para o diretório temporário criado.
+    """
+    # Garante que o diretório base existe
+    config.TEMP_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Cria subdiretório com timestamp
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    temp_path = config.TEMP_DIR / f"{prefix}{timestamp}"
+    temp_path.mkdir(parents=True, exist_ok=True)
+
+    logger.debug(f"Diretório temporário criado: {temp_path}")
+    return temp_path
+
+
+def get_temp_file_path(
+    filename: str,
+    temp_dir: Optional[Path] = None
+) -> Path:
+    """
+    Retorna um caminho de arquivo temporário sanitizado.
+
+    Args:
+        filename: Nome do arquivo (será sanitizado se necessário).
+        temp_dir: Diretório temporário opcional. Se não fornecido, cria um novo.
+
+    Returns:
+        Path completo para o arquivo temporário.
+    """
+    from utils.validators import sanitize_filename
+
+    if temp_dir is None:
+        temp_dir = create_temp_directory()
+
+    safe_filename = sanitize_filename(filename)
+    return temp_dir / safe_filename
+
+
+def cleanup_old_files(
+    max_age_hours: Optional[int] = None,
+    target_dir: Optional[Path] = None
+) -> int:
+    """
+    Remove arquivos temporários mais antigos que o limite especificado.
+
+    Args:
+        max_age_hours: Idade máxima em horas. Se não especificado, usa config.
+        target_dir: Diretório a limpar. Se não especificado, usa TEMP_DIR.
+
+    Returns:
+        Número de arquivos/diretórios removidos.
+    """
+    if max_age_hours is None:
+        max_age_hours = config.TEMP_DIR_CLEANUP_HOURS
+
+    if target_dir is None:
+        target_dir = config.TEMP_DIR
+
+    if not target_dir.exists():
+        return 0
+
+    cutoff_time = time.time() - (max_age_hours * 3600)
+    removed_count = 0
+
+    try:
+        for item in target_dir.iterdir():
+            try:
+                item_stat = item.stat()
+
+                # Usa tempo de modificação
+                if item_stat.st_mtime < cutoff_time:
+                    if item.is_dir():
+                        shutil.rmtree(item)
+                        logger.info(f"Diretório removido: {item}")
+                    else:
+                        item.unlink()
+                        logger.info(f"Arquivo removido: {item}")
+
+                    removed_count += 1
+
+            except PermissionError:
+                logger.warning(f"Sem permissão para remover: {item}")
+            except FileNotFoundError:
+                # Já foi removido
+                pass
+            except Exception as e:
+                logger.error(f"Erro ao remover {item}: {e}")
+
+    except Exception as e:
+        logger.error(f"Erro ao limpar diretório {target_dir}: {e}")
+
+    if removed_count > 0:
+        logger.info(f"Limpeza concluída: {removed_count} itens removidos")
+
+    return removed_count
+
+
+def create_zip_output(
+    files: list[tuple[Path, str]],
+    output_name: str = "resultado"
+) -> Path:
+    """
+    Cria um arquivo ZIP contendo múltiplos arquivos de saída.
+
+    Args:
+        files: Lista de tuplas (caminho_arquivo, nome_no_zip).
+        output_name: Nome base para o arquivo ZIP (sem extensão).
+
+    Returns:
+        Path para o arquivo ZIP criado.
+    """
+    # Cria diretório temporário para o ZIP
+    temp_dir = create_temp_directory(prefix="zip_")
+    zip_path = temp_dir / f"{output_name}.zip"
+
+    try:
+        with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+            for file_path, archive_name in files:
+                if file_path.exists():
+                    zf.write(file_path, archive_name)
+                    logger.debug(f"Adicionado ao ZIP: {archive_name}")
+                else:
+                    logger.warning(f"Arquivo não encontrado para ZIP: {file_path}")
+
+        logger.info(f"ZIP criado: {zip_path} ({len(files)} arquivos)")
+        return zip_path
+
+    except Exception as e:
+        logger.error(f"Erro ao criar ZIP: {e}")
+        raise
+
+
+def copy_file_to_temp(
+    source: Path | str,
+    temp_dir: Optional[Path] = None
+) -> Path:
+    """
+    Copia um arquivo para o diretório temporário.
+
+    Args:
+        source: Caminho do arquivo fonte.
+        temp_dir: Diretório de destino opcional.
+
+    Returns:
+        Path para o arquivo copiado.
+    """
+    source = Path(source)
+
+    if temp_dir is None:
+        temp_dir = create_temp_directory()
+
+    dest_path = temp_dir / source.name
+
+    shutil.copy2(source, dest_path)
+    logger.debug(f"Arquivo copiado: {source} -> {dest_path}")
+
+    return dest_path
+
+
+def save_output_file(
+    content: str | bytes,
+    filename: str,
+    temp_dir: Optional[Path] = None,
+    encoding: str = "utf-8"
+) -> Path:
+    """
+    Salva conteúdo em um arquivo temporário.
+
+    Args:
+        content: Conteúdo a ser salvo (string ou bytes).
+        filename: Nome do arquivo de saída.
+        temp_dir: Diretório de destino opcional.
+        encoding: Encoding para strings (padrão: utf-8).
+
+    Returns:
+        Path para o arquivo salvo.
+    """
+    if temp_dir is None:
+        temp_dir = create_temp_directory(prefix="output_")
+
+    output_path = get_temp_file_path(filename, temp_dir)
+
+    if isinstance(content, str):
+        output_path.write_text(content, encoding=encoding)
+    else:
+        output_path.write_bytes(content)
+
+    logger.debug(f"Arquivo salvo: {output_path}")
+    return output_path
+
+
+def get_temp_dir_size() -> int:
+    """
+    Calcula o tamanho total do diretório temporário.
+
+    Returns:
+        Tamanho em bytes.
+    """
+    if not config.TEMP_DIR.exists():
+        return 0
+
+    total_size = 0
+    for item in config.TEMP_DIR.rglob("*"):
+        if item.is_file():
+            try:
+                total_size += item.stat().st_size
+            except Exception:
+                pass
+
+    return total_size
+
+
+def format_size(size_bytes: int) -> str:
+    """
+    Formata tamanho em bytes para string legível.
+
+    Args:
+        size_bytes: Tamanho em bytes.
+
+    Returns:
+        String formatada (ex: "1.5 MB").
+    """
+    for unit in ["B", "KB", "MB", "GB"]:
+        if size_bytes < 1024:
+            return f"{size_bytes:.1f} {unit}"
+        size_bytes /= 1024
+    return f"{size_bytes:.1f} TB"

utils/logger.py

@@ -0,0 +1,246 @@
+"""
+Sistema de logging para o Docling Document Processor.
+
+Este módulo configura e gerencia o sistema de logging da aplicação,
+incluindo rotação de arquivos e formatação consistente.
+"""
+
+import logging
+import sys
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from typing import Optional
+
+import config
+
+# Flag para evitar configuração duplicada
+_logging_configured = False
+
+# Cache de loggers
+_loggers: dict[str, logging.Logger] = {}
+
+
+def setup_logger(
+    name: str = "docling_space",
+    level: int = logging.INFO,
+    log_to_file: bool = True,
+    log_to_console: bool = True
+) -> logging.Logger:
+    """
+    Configura e retorna um logger.
+
+    Args:
+        name: Nome do logger.
+        level: Nível de logging (default: INFO).
+        log_to_file: Se deve logar em arquivo.
+        log_to_console: Se deve logar no console.
+
+    Returns:
+        Logger configurado.
+    """
+    global _logging_configured
+
+    # Se já existe no cache, retorna
+    if name in _loggers:
+        return _loggers[name]
+
+    # Cria o logger
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    # Evita handlers duplicados
+    if logger.handlers:
+        return logger
+
+    # Formatter
+    formatter = logging.Formatter(
+        config.LOG_FORMAT,
+        datefmt=config.LOG_DATE_FORMAT
+    )
+
+    # Handler de console
+    if log_to_console:
+        console_handler = logging.StreamHandler(sys.stdout)
+        console_handler.setLevel(level)
+        console_handler.setFormatter(formatter)
+        logger.addHandler(console_handler)
+
+    # Handler de arquivo com rotação
+    if log_to_file:
+        try:
+            # Garante que o diretório existe
+            config.LOGS_DIR.mkdir(parents=True, exist_ok=True)
+
+            log_file = config.LOGS_DIR / config.LOG_FILE
+
+            file_handler = RotatingFileHandler(
+                log_file,
+                maxBytes=config.LOG_MAX_BYTES,
+                backupCount=config.LOG_BACKUP_COUNT,
+                encoding="utf-8"
+            )
+            file_handler.setLevel(level)
+            file_handler.setFormatter(formatter)
+            logger.addHandler(file_handler)
+
+        except Exception as e:
+            # Se não conseguir criar o arquivo de log, continua só com console
+            if log_to_console:
+                logger.warning(f"Não foi possível criar arquivo de log: {e}")
+
+    # Não propaga para o root logger
+    logger.propagate = False
+
+    # Adiciona ao cache
+    _loggers[name] = logger
+    _logging_configured = True
+
+    return logger
+
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    """
+    Obtém um logger pelo nome.
+
+    Se o logger não existir, cria um novo com as configurações padrão.
+
+    Args:
+        name: Nome do logger. Se None, usa "docling_space".
+
+    Returns:
+        Logger configurado.
+    """
+    if name is None:
+        name = "docling_space"
+
+    # Se for um nome de módulo completo, usa apenas a última parte
+    if "." in name:
+        short_name = name.split(".")[-1]
+    else:
+        short_name = name
+
+    logger_name = f"docling_space.{short_name}"
+
+    if logger_name not in _loggers:
+        return setup_logger(logger_name)
+
+    return _loggers[logger_name]
+
+
+def log_exception(
+    logger: logging.Logger,
+    message: str,
+    exc: Exception,
+    include_traceback: bool = True
+) -> None:
+    """
+    Loga uma exceção com detalhes.
+
+    Args:
+        logger: Logger a usar.
+        message: Mensagem descritiva.
+        exc: Exceção a logar.
+        include_traceback: Se deve incluir traceback completo.
+    """
+    if include_traceback:
+        logger.exception(f"{message}: {exc}")
+    else:
+        logger.error(f"{message}: {type(exc).__name__}: {exc}")
+
+
+def log_processing_start(
+    logger: logging.Logger,
+    filename: str,
+    file_size: int
+) -> None:
+    """
+    Loga o início do processamento de um arquivo.
+
+    Args:
+        logger: Logger a usar.
+        filename: Nome do arquivo.
+        file_size: Tamanho em bytes.
+    """
+    size_mb = file_size / (1024 * 1024)
+    logger.info(f"Iniciando processamento: {filename} ({size_mb:.2f} MB)")
+
+
+def log_processing_complete(
+    logger: logging.Logger,
+    filename: str,
+    duration_seconds: float,
+    output_format: str
+) -> None:
+    """
+    Loga a conclusão do processamento de um arquivo.
+
+    Args:
+        logger: Logger a usar.
+        filename: Nome do arquivo.
+        duration_seconds: Tempo de processamento em segundos.
+        output_format: Formato de saída usado.
+    """
+    logger.info(
+        f"Processamento concluído: {filename} "
+        f"({duration_seconds:.2f}s, formato: {output_format})"
+    )
+
+
+def log_validation_error(
+    logger: logging.Logger,
+    filename: str,
+    error_code: str,
+    message: str
+) -> None:
+    """
+    Loga um erro de validação.
+
+    Args:
+        logger: Logger a usar.
+        filename: Nome do arquivo.
+        error_code: Código do erro.
+        message: Mensagem de erro.
+    """
+    logger.warning(f"Validação falhou [{error_code}] {filename}: {message}")
+
+
+class ProcessingLogger:
+    """
+    Context manager para logging de processamento.
+
+    Automaticamente loga início e fim do processamento com timing.
+    """
+
+    def __init__(
+        self,
+        logger: logging.Logger,
+        operation: str,
+        filename: str
+    ):
+        self.logger = logger
+        self.operation = operation
+        self.filename = filename
+        self.start_time: float = 0
+
+    def __enter__(self):
+        import time
+        self.start_time = time.time()
+        self.logger.info(f"[INÍCIO] {self.operation}: {self.filename}")
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        import time
+        duration = time.time() - self.start_time
+
+        if exc_type is None:
+            self.logger.info(
+                f"[FIM] {self.operation}: {self.filename} ({duration:.2f}s)"
+            )
+        else:
+            self.logger.error(
+                f"[ERRO] {self.operation}: {self.filename} "
+                f"({duration:.2f}s) - {exc_type.__name__}: {exc_val}"
+            )
+
+        # Não suprime exceções
+        return False

utils/validators.py

@@ -0,0 +1,297 @@
+"""
+Validadores para arquivos de entrada.
+
+Este módulo contém funções para validar arquivos antes do processamento,
+incluindo verificação de tamanho, contagem, MIME type e sanitização de nomes.
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import BinaryIO
+
+import config
+
+# Tenta importar python-magic, mas oferece fallback se não disponível
+try:
+    import magic
+    HAS_MAGIC = True
+except ImportError:
+    HAS_MAGIC = False
+
+
+class ValidationError(Exception):
+    """Exceção levantada quando uma validação falha."""
+
+    def __init__(self, message: str, error_code: str = "VALIDATION_ERROR"):
+        self.message = message
+        self.error_code = error_code
+        super().__init__(self.message)
+
+
+def validate_file_count(files: list) -> bool:
+    """
+    Valida se o número de arquivos está dentro do limite permitido.
+
+    Args:
+        files: Lista de arquivos para validar.
+
+    Returns:
+        True se a contagem está válida.
+
+    Raises:
+        ValidationError: Se houver arquivos demais ou nenhum arquivo.
+    """
+    if not files:
+        raise ValidationError(
+            "Nenhum arquivo enviado. Por favor, selecione ao menos um arquivo.",
+            error_code="NO_FILES"
+        )
+
+    if len(files) > config.MAX_FILES_PER_SESSION:
+        raise ValidationError(
+            f"Muitos arquivos! Máximo permitido: {config.MAX_FILES_PER_SESSION}. "
+            f"Você enviou: {len(files)}.",
+            error_code="TOO_MANY_FILES"
+        )
+
+    return True
+
+
+def validate_file_size(file_path: str | Path) -> bool:
+    """
+    Valida se o tamanho do arquivo está dentro do limite permitido.
+
+    Args:
+        file_path: Caminho para o arquivo a ser validado.
+
+    Returns:
+        True se o tamanho está válido.
+
+    Raises:
+        ValidationError: Se o arquivo for muito grande.
+    """
+    file_path = Path(file_path)
+
+    if not file_path.exists():
+        raise ValidationError(
+            f"Arquivo não encontrado: {file_path.name}",
+            error_code="FILE_NOT_FOUND"
+        )
+
+    file_size = file_path.stat().st_size
+
+    if file_size > config.MAX_FILE_SIZE_BYTES:
+        size_mb = file_size / (1024 * 1024)
+        raise ValidationError(
+            f"Arquivo muito grande: {file_path.name} ({size_mb:.1f}MB). "
+            f"Máximo permitido: {config.MAX_FILE_SIZE_MB}MB.",
+            error_code="FILE_TOO_LARGE"
+        )
+
+    if file_size == 0:
+        raise ValidationError(
+            f"Arquivo vazio: {file_path.name}",
+            error_code="EMPTY_FILE"
+        )
+
+    return True
+
+
+def _get_mime_type_magic(file_path: str | Path) -> str:
+    """
+    Obtém o MIME type usando python-magic.
+
+    Args:
+        file_path: Caminho para o arquivo.
+
+    Returns:
+        String com o MIME type detectado.
+    """
+    mime = magic.Magic(mime=True)
+    return mime.from_file(str(file_path))
+
+
+def _get_mime_type_fallback(file_path: str | Path) -> str:
+    """
+    Fallback para detecção de MIME type sem python-magic.
+    Usa assinaturas de arquivo (magic bytes).
+
+    Args:
+        file_path: Caminho para o arquivo.
+
+    Returns:
+        String com o MIME type detectado ou extensão-based guess.
+    """
+    file_path = Path(file_path)
+
+    # Magic bytes para tipos comuns
+    signatures = {
+        b"%PDF": "application/pdf",
+        b"PK\x03\x04": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        b"\xd0\xcf\x11\xe0": "application/msword",  # OLE Compound Document
+    }
+
+    try:
+        with open(file_path, "rb") as f:
+            header = f.read(8)
+
+        for sig, mime_type in signatures.items():
+            if header.startswith(sig):
+                return mime_type
+    except Exception:
+        pass
+
+    # Fallback para extensão
+    ext = file_path.suffix.lower()
+    ext_to_mime = {
+        ".pdf": "application/pdf",
+        ".doc": "application/msword",
+        ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    }
+
+    return ext_to_mime.get(ext, "application/octet-stream")
+
+
+def get_mime_type(file_path: str | Path) -> str:
+    """
+    Obtém o MIME type de um arquivo.
+
+    Usa python-magic se disponível, caso contrário usa fallback
+    baseado em assinaturas de arquivo.
+
+    Args:
+        file_path: Caminho para o arquivo.
+
+    Returns:
+        String com o MIME type detectado.
+    """
+    if HAS_MAGIC:
+        return _get_mime_type_magic(file_path)
+    return _get_mime_type_fallback(file_path)
+
+
+def validate_mime_type(file_path: str | Path) -> bool:
+    """
+    Valida se o MIME type do arquivo é suportado.
+
+    Args:
+        file_path: Caminho para o arquivo a ser validado.
+
+    Returns:
+        True se o MIME type é válido.
+
+    Raises:
+        ValidationError: Se o tipo de arquivo não for suportado.
+    """
+    file_path = Path(file_path)
+    extension = file_path.suffix.lower()
+
+    # Verifica se a extensão é suportada
+    if extension not in config.SUPPORTED_EXTENSIONS:
+        raise ValidationError(
+            f"Extensão não suportada: {extension}. "
+            f"Tipos aceitos: {', '.join(config.SUPPORTED_EXTENSIONS)}",
+            error_code="UNSUPPORTED_EXTENSION"
+        )
+
+    # Obtém o MIME type real do arquivo
+    detected_mime = get_mime_type(file_path)
+
+    # Verifica se o MIME type corresponde à extensão
+    expected_mimes = config.SUPPORTED_MIME_TYPES.get(extension, [])
+
+    if detected_mime not in expected_mimes:
+        # DOCX pode ser detectado como ZIP em alguns casos
+        if extension == ".docx" and detected_mime == "application/zip":
+            return True
+
+        raise ValidationError(
+            f"Tipo de arquivo inválido: {file_path.name}. "
+            f"O conteúdo não corresponde à extensão {extension}. "
+            f"Detectado: {detected_mime}",
+            error_code="MIME_MISMATCH"
+        )
+
+    return True
+
+
+def sanitize_filename(filename: str) -> str:
+    """
+    Remove caracteres especiais/perigosos do nome de arquivo.
+
+    Args:
+        filename: Nome original do arquivo.
+
+    Returns:
+        Nome de arquivo sanitizado.
+    """
+    if not filename:
+        return "arquivo_sem_nome"
+
+    # Remove caracteres proibidos
+    for char in config.FORBIDDEN_FILENAME_CHARS:
+        filename = filename.replace(char, "_")
+
+    # Remove caracteres de controle
+    filename = re.sub(r"[\x00-\x1f\x7f]", "", filename)
+
+    # Substitui espaços múltiplos por um único underscore
+    filename = re.sub(r"\s+", "_", filename)
+
+    # Remove underscores múltiplos
+    filename = re.sub(r"_+", "_", filename)
+
+    # Remove underscores no início e fim
+    filename = filename.strip("_")
+
+    # Limita o comprimento
+    if len(filename) > config.FILENAME_MAX_LENGTH:
+        # Preserva a extensão
+        name, ext = os.path.splitext(filename)
+        max_name_len = config.FILENAME_MAX_LENGTH - len(ext)
+        filename = name[:max_name_len] + ext
+
+    # Se ficou vazio após sanitização
+    if not filename or filename == "." or filename == "..":
+        return "arquivo_sanitizado"
+
+    return filename
+
+
+def validate_files(files: list) -> list[tuple[Path, str]]:
+    """
+    Valida uma lista de arquivos completamente.
+
+    Args:
+        files: Lista de arquivos (podem ser paths ou objetos de arquivo).
+
+    Returns:
+        Lista de tuplas (path, nome_sanitizado) para arquivos válidos.
+
+    Raises:
+        ValidationError: Se qualquer validação falhar.
+    """
+    validate_file_count(files)
+
+    validated = []
+
+    for file_obj in files:
+        # Gradio retorna objetos com atributo 'name'
+        if hasattr(file_obj, "name"):
+            file_path = Path(file_obj.name)
+        else:
+            file_path = Path(file_obj)
+
+        # Valida tamanho
+        validate_file_size(file_path)
+
+        # Valida MIME type
+        validate_mime_type(file_path)
+
+        # Sanitiza nome
+        sanitized_name = sanitize_filename(file_path.name)
+
+        validated.append((file_path, sanitized_name))
+
+    return validated