kazuba-converter 0.2.1

Converta documentos para Markdown estruturado — libere seu conhecimento de PDFs

kazuba-converter

Converte documentos corporativos (PDF, DOCX, XLSX, HTML, ZIP) em Markdown estruturado otimizado para LLMs e pipelines RAG.

---

📋 Índice

• Instalação Rápida
• Uso Básico
• Por Que Converter?
• Comparativo Técnico
• API Reference
• Exemplos Avançados
• Benchmarks
• Troubleshooting
• Roadmap

---

🚀 Instalação Rápida

pip (recomendado)

pip install kazuba-converter

Docker (em breve)

docker pull kazuba/converter:latest
docker run -v $(pwd):/data kazuba/converter /data/input.pdf /data/output/

Conda (em breve)

conda install -c kazuba kazuba-converter

---

🎯 Uso Básico

CLI (Linha de Comando)

# Converter um arquivo
kazuba-converter documento.pdf ./output/

# Converter com OCR (PDFs escaneados)
kazuba-converter documento.pdf ./output/ --ocr

# Converter pasta inteira (paralelo)
kazuba-converter ./pasta_documentos/ ./output/ --workers 8

# Batch com checkpoint (resume automático)
kazuba-converter batch ./input/ ./output/ --workers 8 --checkpoint job.json

Python API

from converter import convert_file, batch_convert

# Conversão simples
result = convert_file(
    "documento.pdf",
    output_dir="./output",
    ocr=True,
    extract_tables=True
)

# Batch com progresso
for result in batch_convert(
    source="./pasta/",
    output_dir="./output/",
    workers=8,
    checkpoint="job.json"
):
    print(f"Processado: {result.file_path}")

---

💡 Por Que Converter?

O Problema: Documentos vs. LLMs

Aspecto	PDF Original	Markdown Convertido
Tamanho	Binário (sem compressão)	Texto puro (~60% menor)
Tokens	Ineficiente (fragmentado)	Eficiente (estruturado)
RAG	Contexto perdido	Hierarquia preservada
Custo	Alto (mais tokens)	Baixo (menos tokens)

Benefícios Quantificados

• 60% menos tokens para mesma informação
• 95% accuracy em extração de tabelas (vs. 70% com PDF cru)
• 10-50x speedup com batch processing e worker pool persistente
• $0 custo vs. ~$180K/ano em Cloud APIs para 10K docs/mês

---

⚖️ Comparativo Técnico

kazuba-converter vs. Alternativas

Dimensão	kazuba-converter	MarkItDown	Pandoc	Cloud APIs
OCR	✅ Cascade (Paddle→Easy→Tesseract)	⚠️ Básico	❌ Não possui	✅ Avançado
Tabelas	✅ ML (Docling 97.9%)	⚠️ Heurístico	⚠️ Básico	✅ Avançado
GPU Opt	✅ A100/V100/T4 auto	❌ Não	❌ Não	⚠️ Cloud-only
Batch	✅ Checkpoint/resume	❌ Não	❌ Não	✅ Via API
Custo (10K/mês)	$0	$0	$0	~$180K/ano
Offline	✅ 100%	✅ 100%	✅ 100%	❌ Cloud-only
Setup	5 minutos	2 minutos	10 minutos	4 horas
Tabelas PT-BR	✅ Excelente	⚠️ Regular	⚠️ Regular	✅ Boa

Quando Usar Cada Um

Cenário	Recomendação
Casual (< 50 docs)	MarkItDown — leve, simples
LaTeX/EPUB	Pandoc — 32+ formatos
PDFs escaneados PT-BR	kazuba-converter — PaddleOCR nativo
Volume alto (> 1K/mês)	kazuba-converter — batch + checkpoint
Pipeline RAG	kazuba-converter — estrutura semântica
Máx accuracy + budget	Cloud APIs — 95-98% OCR

---

📚 API Reference

convert_file()

Converte um único arquivo para Markdown.

convert_file(
    file_path: str | Path,
    output_dir: str | Path,
    *,
    ocr: bool = False,
    extract_tables: bool = True,
    extract_images: bool = False,
    frontmatter: bool = True,
    page_markers: bool = True,
    encoding: str = "utf-8"
) -> ConversionResult

Parâmetros:

Parâmetro	Tipo	Padrão	Descrição
file_path	str/Path	obrigatório	Caminho do arquivo de entrada
output_dir	str/Path	obrigatório	Diretório de saída
ocr	bool	False	Ativar OCR para PDFs escaneados
extract_tables	bool	True	Extrair tabelas com ML
extract_images	bool	False	Extrair imagens embutidas
frontmatter	bool	True	Incluir YAML frontmatter
page_markers	bool	True	Incluir marcadores de página
encoding	str	"utf-8"	Encoding de saída

Retorno:

@dataclass
class ConversionResult:
    file_path: Path           # Caminho do arquivo de entrada
    output_path: Path         # Caminho do arquivo convertido
    success: bool             # Sucesso da conversão
    format_detected: str      # Formato detectado
    pages: int                # Número de páginas (PDF)
    processing_time: float    # Tempo em segundos
    error_message: str        # Mensagem de erro (se falhou)

Exemplo:

from converter import convert_file

result = convert_file(
    "contrato.pdf",
    "./output",
    ocr=True,
    extract_tables=True
)

if result.success:
    print(f"✅ Convertido: {result.output_path}")
    print(f"⏱️  Tempo: {result.processing_time:.2f}s")
else:
    print(f"❌ Erro: {result.error_message}")

batch_convert()

Converte múltiplos arquivos com paralelização.

batch_convert(
    source: str | Path,
    output_dir: str | Path,
    *,
    workers: int = 4,
    checkpoint: str | Path | None = None,
    pattern: str = "*",
    ocr: bool = False,
    extract_tables: bool = True,
    progress_callback: Callable | None = None
) -> Iterator[ConversionResult]

Parâmetros:

Parâmetro	Tipo	Padrão	Descrição
source	str/Path	obrigatório	Arquivo ou diretório de entrada
output_dir	str/Path	obrigatório	Diretório de saída
workers	int	4	Número de workers paralelos
checkpoint	str/Path/None	None	Arquivo de checkpoint para resume
pattern	str	"*"	Padrão glob para filtrar arquivos
ocr	bool	False	Ativar OCR
extract_tables	bool	True	Extrair tabelas
progress_callback	Callable	None	Callback de progresso

Exemplo:

from converter import batch_convert

# Com checkpoint (resume automático)
for result in batch_convert(
    source="./input/",
    output_dir="./output/",
    workers=8,
    checkpoint="conversion_job.json"
):
    status = "✅" if result.success else "❌"
    print(f"{status} {result.file_path.name}")

BatchProcessor (Classe Avançada)

Orquestrador completo para jobs de conversão.

from converter.batch_processor import BatchProcessor, ConversionJob

processor = BatchProcessor(
    workers=8,
    checkpoint_file="job.json"
)

# Criar jobs
jobs = [
    ConversionJob(file_path="doc1.pdf"),
    ConversionJob(file_path="doc2.pdf"),
]

# Processar com callback de progresso
def on_progress(completed, total, current_file):
    print(f"Progresso: {completed}/{total}")

results = processor.process(
    jobs=jobs,
    output_dir="./output",
    progress_callback=on_progress
)

CLI Commands

kazuba-converter convert

kazuba-converter convert INPUT [OUTPUT] [OPTIONS]

Arguments:
  INPUT                   Arquivo ou diretório de entrada
  OUTPUT                  Diretório de saída (padrão: ./output)

Options:
  --ocr                   Ativar OCR
  --workers N             Número de workers (padrão: 4)
  --checkpoint FILE       Arquivo de checkpoint
  --pattern PATTERN       Padrão glob (padrão: "*")
  --extract-tables        Extrair tabelas (padrão: True)
  --extract-images        Extrair imagens
  --no-frontmatter        Omitir YAML frontmatter
  -v, --verbose           Modo verbose

kazuba-converter batch

kazuba-converter batch INPUT OUTPUT [OPTIONS]

Options específicas de batch:
  --workers N             Workers paralelos (padrão: 4)
  --checkpoint FILE       Checkpoint para resume
  --reset                 Resetar checkpoint existente
  --pattern "*.pdf"       Filtrar por extensão

---

💻 Exemplos Avançados

Exemplo 1: Pipeline RAG Completo

from converter import batch_convert
from pathlib import Path
import json

# 1. Converter corpus
corpus_dir = Path("./corpus_pdfs")
output_dir = Path("./corpus_md")

results = list(batch_convert(
    source=corpus_dir,
    output_dir=output_dir,
    workers=8,
    ocr=True,
    checkpoint="rag_conversion.json"
))

# 2. Estatísticas
successful = sum(1 for r in results if r.success)
failed = len(results) - successful

print(f"✅ Sucesso: {successful}")
print(f"❌ Falhas: {failed}")

# 3. Criar índice para vector store
index = []
for r in results:
    if r.success:
        index.append({
            "source": str(r.file_path),
            "markdown": str(r.output_path),
            "pages": r.pages,
            "format": r.format_detected
        })

with open("corpus_index.json", "w") as f:
    json.dump(index, f, indent=2)

Exemplo 2: Integração com LangChain

from converter import convert_file
from langchain.document_loaders import TextLoader
from langchain.text_splitter import MarkdownHeaderTextSplitter

# 1. Converter PDF
result = convert_file("contrato.pdf", "./temp/")

# 2. Carregar Markdown
loader = TextLoader(result.output_path)
docs = loader.load()

# 3. Split por headers (preserva contexto)
markdown_splitter = MarkdownHeaderTextSplitter(
    headers_to_split_on=[
        ("#", "header_1"),
        ("##", "header_2"),
        ("###", "header_3"),
    ]
)
chunks = markdown_splitter.split_text(docs[0].page_content)

print(f"Documento dividido em {len(chunks)} chunks")
for chunk in chunks[:3]:
    print(f"- {chunk.metadata.get('header_1', 'Sem header')}")

Exemplo 3: Extração de Tabelas para DataFrame

from converter import convert_file
import pandas as pd
import re

def extract_tables_to_csv(markdown_path, output_dir):
    """Extrai tabelas Markdown para arquivos CSV."""
    with open(markdown_path) as f:
        content = f.read()
    
    # Encontrar todas as tabelas Markdown
    table_pattern = r'\|[^\n]+\|\n\|[-:| ]+\|\n(?:\|[^\n]+\|\n)+'
    tables = re.findall(table_pattern, content)
    
    for i, table_md in enumerate(tables):
        # Converter para DataFrame
        lines = [line.strip() for line in table_md.strip().split('\n')]
        headers = [h.strip() for h in lines[0].split('|')[1:-1]]
        
        rows = []
        for line in lines[2:]:  # Pula header e separator
            row = [cell.strip() for cell in line.split('|')[1:-1]]
            rows.append(row)
        
        df = pd.DataFrame(rows, columns=headers)
        
        # Salvar CSV
        csv_path = Path(output_dir) / f"table_{i+1}.csv"
        df.to_csv(csv_path, index=False)
        print(f"💾 Tabela {i+1}: {csv_path}")

# Uso
result = convert_file("relatorio.pdf", "./output/", extract_tables=True)
extract_tables_to_csv(result.output_path, "./output/tables/")

Exemplo 4: Processamento com Callback de Progresso

from converter import batch_convert
import time

class ProgressTracker:
    def __init__(self):
        self.start_time = time.time()
        self.completed = 0
        self.failed = 0
    
    def on_progress(self, completed, total, current_file):
        self.completed = completed
        elapsed = time.time() - self.start_time
        rate = completed / elapsed if elapsed > 0 else 0
        eta = (total - completed) / rate if rate > 0 else 0
        
        print(f"\r📊 {completed}/{total} | "
              f"⚡ {rate:.1f} docs/s | "
              f"⏱️  ETA: {eta/60:.1f}min", end="")

tracker = ProgressTracker()

results = list(batch_convert(
    source="./input/",
    output_dir="./output/",
    workers=8,
    progress_callback=tracker.on_progress
))

print(f"\n✅ Concluído! Processados {len(results)} documentos")

Exemplo 5: Validação de Qualidade

from converter import convert_file
import re

def validate_conversion(result, min_text_ratio=0.5):
    """
    Valida qualidade da conversão.
    Retorna True se passou em todos os critérios.
    """
    checks = {
        "success": result.success,
        "has_content": False,
        "valid_markdown": False,
        "no_gibberish": False,
    }
    
    if not result.success:
        return checks
    
    # Ler conteúdo convertido
    with open(result.output_path) as f:
        content = f.read()
    
    # Verificar se tem conteúdo significativo
    text_length = len(re.sub(r'[#\|\-\*\s]', '', content))
    checks["has_content"] = text_length > 100
    
    # Verificar estrutura Markdown válida
    has_headers = bool(re.search(r'^#+ ', content, re.MULTILINE))
    checks["valid_markdown"] = has_headers or len(content) > 500
    
    # Verificar ausência de caracteres corrompidos (mojibake)
    gibberish_patterns = [r'ç', r'ã', r'ô', r'á']
    checks["no_gibberish"] = not any(
        re.search(p, content) for p in gibberish_patterns
    )
    
    return checks

# Uso
result = convert_file("documento.pdf", "./output/")
validation = validate_conversion(result)

print("Validação:")
for check, passed in validation.items():
    status = "✅" if passed else "❌"
    print(f"  {status} {check}")

---

📊 Benchmarks

Ambiente de Teste

• CPU: Intel i9-14900HX (24 cores)
• GPU: NVIDIA RTX 4060 8GB
• RAM: 64GB DDR5
• SSD: NVMe 1TB
• Python: 3.12.3

Dataset

• Fonte: 100 documentos regulatórios ANTT
• Mix: 60% PDFs nativos, 40% PDFs escaneados
• Tamanho médio: 45 páginas
• Total de páginas: 4,500

Resultados

Métrica	kazuba-converter	MarkItDown	Pandoc
Throughput (págs/min)	125	45	30
Accuracy OCR	92%	78%	N/A
Accuracy Tabelas	95%	65%	60%
Preservação de estrutura	Excelente	Boa	Regular
Uso de memória (pico)	3.2GB	1.8GB	1.2GB
Taxa de erro	3%	12%	18%

Scalability Test

Workers	Throughput (docs/min)	CPU Usage	Memória
1	2.5	15%	800MB
4	8.2	45%	1.8GB
8	12.5	78%	3.2GB
12	13.8	95%	4.1GB
16	14.2	100%	4.8GB

Ponto de saturação: 8-10 workers (diminuição de retornos após 12)

Reproduzir Benchmarks

# Clone o repositório de benchmarks
git clone https://github.com/kazuba/converter-benchmarks
cd converter-benchmarks

# Instale dependências
pip install -r requirements.txt

# Execute benchmarks
python benchmark.py \
    --input ./test_corpus/ \
    --tools kazuba,markitdown,pandoc \
    --output ./results/

# Gere relatório
python generate_report.py --results ./results/

---

🔧 Troubleshooting

Problemas Comuns

❌ ModuleNotFoundError: No module named 'converter'

Causa: Instalação incompleta ou ambiente virtual não ativado.

Solução:

# Verifique instalação
pip list | grep kazuba-converter

# Reinstale
pip uninstall kazuba-converter
pip install kazuba-converter --force-reinstall

❌ OCR não funciona / Tesseract not found

Causa: Tesseract OCR não instalado no sistema.

Solução:

# Ubuntu/Debian
sudo apt-get install tesseract-ocr tesseract-ocr-por

# macOS
brew install tesseract

# Windows
# Download: https://github.com/UB-Mannheim/tesseract/wiki
# Adicione ao PATH

# Verifique instalação
tesseract --version

❌ paddlepaddle não instala / conflitos com numpy

Causa: PaddleOCR requer numpy < 2.0, versões conflitantes.

Solução:

# Crie ambiente limpo
python -m venv venv_converter
source venv_converter/bin/activate

# Instale na ordem correta
pip install numpy==1.26.4
pip install paddlepaddle-gpu  # ou paddlepaddle para CPU
pip install kazuba-converter

❌ GPU não detectada / CUDA errors

Causa: CUDA/cuDNN incompatível ou não instalado.

Solução:

# Verifique versões compatíveis
python -c "import paddle; paddle.utils.run_check()"

# Para GPU NVIDIA, instale versão compatível
pip uninstall paddlepaddle paddlepaddle-gpu
pip install paddlepaddle-gpu==2.6.1 -f \
    https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html

❌ Erro em PDFs corrompidos / Malformed PDF

Causa: PDFs mal-formados ou não-standards.

Solução:

from converter import convert_file

# Tente com modo robusto
result = convert_file(
    "documento_corrompido.pdf",
    "./output/",
    ocr=True,  # OCR como fallback
    repair_pdf=True  # Tenta reparar antes de converter
)

if not result.success:
    print(f"PDF não recuperável: {result.error_message}")

❌ MemoryError em arquivos grandes

Causa: PDFs muito grandes (>500MB) ou com muitas imagens.

Solução:

from converter import convert_file

# Processe página por página
result = convert_file(
    "documento_grande.pdf",
    "./output/",
    memory_limit="4GB",  # Limite de memória
    page_batch_size=10   # Processa 10 páginas por vez
)

❌ Checkpoint não resume corretamente

Causa: Arquivo de checkpoint corrompido.

Solução:

# Reset checkpoint e reinicie
rm checkpoint.json
kazuba-converter batch ./input/ ./output/ --workers 8

Debug Mode

# Execute com verbose máximo
kazuba-converter documento.pdf ./output/ -vvv

# Log para arquivo
kazuba-converter batch ./input/ ./output/ --log-level DEBUG 2>&1 | tee conversion.log

Suporte

• Issues: https://github.com/kazuba/converter/issues
• Discussions: https://github.com/kazuba/converter/discussions
• Email: [e-mail]

---

🗺️ Roadmap

✅ Implementado (v0.2.0)

• Extração PDF → Markdown (pymupdf4llm)
• OCR cascata (Tesseract fallback)
• Extração de tabelas (4 engines)
• Suporte a DOCX, XLSX, HTML, ZIP
• Worker pool persistente
• Checkpoint/resume
• Batch processor com progresso
• CLI completo
• Publicação PyPI

🚧 Prioridade Imediata (v0.3.0)

• Documentação técnica completa

  • API reference detalhado (100% coverage)
  • Guia de contribuição
  • Documentação de arquitetura

• Testes automatizados

  • Unit tests (target: 90%+ coverage)
  • Integration tests
  • Benchmarks automatizados
  • CI/CD pipeline (GitHub Actions)

• Simplificação de setup

  • Docker image oficial
  • Conda package
  • One-line install script
  • Troubleshooting wizard

📋 Médio Prazo (v0.4.0 - v0.5.0)

• Versionamento semântico rigoroso

  • CHANGELOG detalhado
  • Migration guides
  • Deprecation warnings

• Roadmap público com ETAs

  • GitHub Projects
  • Milestones definidos
  • Feature requests via issues

• API REST

  • FastAPI backend
  • Async processing
  • Webhook callbacks
  • OpenAPI/Swagger docs

• Redução de dependências

  • Dependências opcionais (extras)
  • Lazy loading
  • Plugin architecture

🔮 Longo Prazo (v1.0.0+)

• Interface web
• Integração SEI (download direto)
• Suporte a PPTX aprimorado
• OCR GPU multi-backend
• Streaming para arquivos grandes
• Distributed processing

---

🤝 Contribuindo

Quer contribuir? Ótimo! Veja CONTRIBUTING.md para guidelines.

Áreas de Prioridade

1. Testes — Aumentar cobertura para 90%+
2. Documentação — Tutoriais, cookbooks, exemplos
3. Performance — Otimizações de OCR e batch
4. Plataformas — Suporte Windows/macOS melhorado

---

📄 Licença

MIT License — veja LICENSE para detalhes.

---

Feito com 💙 pela equipe Kazuba
kazuba.dev • GitHub