jiawood2006/hermes-skills

Doc-OCR: reconocimiento de documentos + estructuración

PDF / escaneos / imágenes → texto editable → datos estructurados. Los PDFs con capa de texto se extraen directamente; los escaneos se procesan automáticamente con OCR (macOS Vision integrado, para chino e inglés). Se preserva la estructura de la página (columnas múltiples y diseños complejos se reorganizan según el orden de lectura, sin líneas desnudas). Después del OCR, se puede usar un LLM para extraer campos de facturas y contratos, o convertir tablas.

📁 Instalación: hermes skills install jiawood2006/hermes-skills/skills/doc-ocr o, siguiendo el método 2 del README, copiarlo a la ruta predeterminada ~/.hermes/skills/utilities/doc-ocr/. Los comandos siguientes se basan en esa ruta.

Condiciones de activación

El usuario proporciona un archivo PDF o imagen y solicita:

• "Extraer texto", "Convertir a texto", "OCR"
• Procesar escaneos, contratos, facturas, páginas de libros, capturas de pantalla
• "Extraer información de factura", "Puntos clave del contrato", "Convertir a tabla" (estructuración)

Instrucciones de uso

1. Archivo individual → texto

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

La salida se guarda como <nombre_de_entrada>_ocr.txt.

2. Directorio por lotes (tolerancia a fallos por archivo, no se interrumpe por archivos dañados)

python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py ./escaneos/ -o todo.txt
# Resumen de salida al finalizar: N/M exitosos + lista de fallos (archivos dañados se registran individualmente sin interrumpir el lote)

3. Salida en Markdown / Forzar reestructuración de diseño en PDFs con varias columnas

python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py libro.pdf --md
# Cuando la capa de texto de un PDF con varias columnas está desordenada, forzar OCR con Vision para reestructurar:
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py articulo_doble_columna.pdf --md --force-ocr

4. Extracción estructurada (factura/contrato/tabla, requiere clave de LLM)

# Primero OCR, luego extraer campos
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py factura.jpg
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py factura_ocr.txt --type invoice

# Campos de contrato (partes A/B, monto, plazo, cláusulas de penalización)
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py contrato_ocr.txt --type contract

# Tabla → CSV
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py tabla_ocr.txt --type table -o tabla.csv

• --type invoice: número de factura, fecha, monto, impuesto, total impuestos incluidos, comprador, vendedor, CUIT
• --type contract: nombre del contrato, partes A y B, fecha de firma, monto, método de pago, plazo, cláusulas de penalización
• --type table: identifica automáticamente la estructura de filas y columnas → CSV
• Salida amigable + posibilidad de guardar en JSON/CSV (con -o)

Dependencias (instalar en el primer uso)

pip3 install pymupdf pyobjc-framework-Vision
# Para extracción estructurada se necesita una clave de LLM (variable de entorno LLM_API_KEY o archivo ~/.deai_writer.conf)

Nota: El OCR depende de macOS Vision (solo disponible en macOS). En Linux se necesita instalar otros motores como tesseract.

Errores conocidos

• Detección de escaneo: los PDFs con menos de 20 caracteres en la capa de texto se procesan automáticamente con OCR; los PDFs normales se extraen directamente.
• Reestructuración de diseño: Vision OCR reorganiza el texto según las coordenadas de los cuadros de texto (de arriba abajo, de izquierda a derecha en la misma línea); los impresos de doble columna se tratan como "primero columna izquierda, luego derecha", adecuado para artículos e informes. Los diseños de revistas pueden seguir desordenados; usar --force-ocr y verificar visualmente.
• Escritura a mano: Vision funciona bien con texto impreso y escritura clara, no garantiza resultados con escritura ilegible.
• Ventaja de privacidad: los archivos se procesan localmente, no se suben a terceros (la extracción estructurada llama a la API del LLM; tener cuidado con archivos sensibles).
• Campos faltantes: docstruct rellena los campos faltantes con null sin inventarlos; si la calidad del OCR es baja, puede faltar algún campo.
• Tolerancia a fallos en lotes: en modo directorio, si falla un archivo individual, se registra en el resumen sin interrumpir todo el lote.

Prueba rápida / Smoke Test

# Verificación de instalación (funciona incluso sin documentos a mano)
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py --help
# Verificación real con cualquier PDF o imagen
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py cualquier_documento.pdf --md
# Resultado esperado: salida *_ocr.md con texto editable