jiawood2006/hermes-skills

Doc-OCR 文档识别 + 结构化 (Reconhecimento de Documentos + Estruturação)

PDF / digitalizações / imagens → texto editável → dados estruturados. PDFs com camada de texto são extraídos diretamente; digitalizações passam por OCR automático (macOS Vision nativo, português/inglês) com reconstrução de layout (colunas múltiplas / layouts complexos são reordenados em ordem de leitura, não são linhas soltas). Após o OCR, é possível usar um LLM para extrair campos de faturas e contratos, ou converter para tabelas.

📁 Instalação: hermes skills install jiawood2006/hermes-skills/skills/doc-ocr ou siga o método descrito no README → o padrão fica em ~/.hermes/skills/utilities/doc-ocr/. Os comandos a seguir são baseados nesse caminho.

Condições de Ativação

O usuário fornece um arquivo PDF/imagem e solicita:

• "Extrair texto""Converter para texto""OCR"
• Processar digitalizações, contratos, faturas, páginas de livros, capturas de tela
• "Extrair dados da fatura""Pontos principais do contrato""Converter para tabela" (estruturação)

Etapas de Uso

1. Arquivo único → Texto

python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py contrato.pdf
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py fatura.jpg

A saída é salva como <nome_do_arquivo>_ocr.txt.

2. Lote de diretório (tolerante a falhas por arquivo, sem interrupção no lote)

python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py ./digitalizacoes/ -o tudo.txt
# Resumo da conclusão do lote: N/M sucessos + lista de falhas (arquivos corrompidos registrados sem interromper o lote)

3. Saída Markdown / Forçar reconstrução de layout para PDFs com múltiplas colunas

python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py livro.pdf --md
# Para PDFs com falha na ordem da camada de texto (colunas), forçar reconstrução via Vision OCR:
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py artigo_duas_colunas.pdf --md --force-ocr

4. Extração estruturada (faturas/contratos/tabelas, requer chave LLM)

# Primeiro fazer OCR, depois extrair campos
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py fatura.jpg
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py fatura_ocr.txt --type invoice

# Campos de contrato (partes/valor/prazo/cláusulas de penalidade)
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py contrato_ocr.txt --type contract

# Tabela → CSV
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py tabela_ocr.txt --type table -o tabela.csv

• --type invoice: número da fatura/data/valor/imposto/total/comprador/vendedor/CNPJ
• --type contract: nome do contrato/partes/data de assinatura/valor/forma de pagamento/prazo/cláusulas de penalidade
• --type table: reconhecimento automático de estrutura de linhas/colunas → CSV
• Saída amigável para exibição + possibilidade de salvar em JSON/CSV (-o)

Dependências (instalar no primeiro uso)

pip3 install pymupdf pyobjc-framework-Vision
# Extração estruturada requer chave LLM (variável de ambiente LLM_API_KEY ou ~/.deai_writer.conf)

Aviso: OCR depende de macOS Vision (apenas macOS). No Linux, será necessário instalar outros mecanismos como tesseract.

Armadilhas Conhecidas

• Detecção de digitalização: PDFs com <20 caracteres na camada de texto são automaticamente submetidos a OCR; PDFs normais são extraídos diretamente.
• Reconstrução de layout: O Vision OCR reordena com base nas coordenadas dos bounding boxes (de cima para baixo, da esquerda para a direita na mesma linha); impressos com duas colunas são tratados como "coluna da esquerda primeiro, depois da direita", adequado para artigos/relatórios, mas layouts de revista podem ainda sair fora de ordem — use --force-ocr e inspeção visual.
• Manuscritos: Vision tem bons resultados com texto impresso e manuscrito legível, mas não garante precisão para letras muito ilegíveis.
• Privacidade: Os arquivos são processados localmente, não enviados a terceiros (a extração estruturada chama a API do LLM, cuidado com documentos sensíveis).
• Campos ausentes: docstruct preenche campos ausentes com null e não inventa; se o OCR for de baixa qualidade, haverá menos campos.
• Tolerância a falhas em lote: No modo diretório, falhas em arquivos individuais são registradas no resumo, mas não interrompem o lote.

Teste Rápido / Smoke Test

# Verificação de instalação (funciona mesmo sem documentos disponíveis)
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py --help
# Teste real com qualquer PDF/imagem disponível
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py qualquer_documento.pdf --md
# Esperado: saída *_ocr.md com texto editável

---

Skill Original: jiawood2006/hermes-skills (por jiawood2006)