Extracción de Documentos — de Escaneos a Texto

Imagina que le pasas un contrato a un compañero y, al hojearlo, te dice: “Esto son todo imágenes, no puedo leer ni una palabra”. Ese es exactamente el problema que solucionamos hoy. La herramienta read_file de Hermes Agent ahora puede “abrir” archivos como lo haría un humano: convirtiendo PDFs, documentos de Word, hojas de Excel e incluso archivos Office heredados en texto plano que realmente puede entender.

Tres formatos, cero configuración

Los formatos más comunes funcionan directamente, sin necesidad de instalar nada:

Cuadernos de Jupyter (.ipynb)
Documentos de Word (.docx)
Hojas de cálculo de Excel (.xlsx)

Estos se convierten a texto Markdown y admiten lectura paginada mediante los parámetros offset y limit, igual que pasar las páginas de un libro, una a una.

Todo lo demás: autoinstalado, sin preocupaciones

Para PDFs, archivos Office heredados (.doc, .ppt, .xls), OpenDocument y libros electrónicos (.epub), Hermes instala automáticamente un conversor llamado firecrawl-anydoc en el primer uso. No tienes que mover ni un dedo.

Un detalle: si la configuración de tu sistema desactiva la autoinstalación (security.allow_lazy_installs en false), solo funcionarán los tres formatos integrados; todo lo demás se tratará como binario. Además, los archivos de más de 50 MB se rechazan para evitar tiempos de procesamiento excesivamente largos.

También funciona en entornos remotos

Tanto si tu código se ejecuta en Docker, Modal o un servidor remoto por SSH, los archivos se transfieren automáticamente a tu máquina local para su conversión. Leer un documento en un entorno aislado funciona exactamente igual que leerlo localmente.

La gran advertencia: los escaneos son “PDFs falsos”

Aquí está la trampa: la conversión de PDF solo lee la capa de texto. Si un PDF es un escaneo (contratos en papel, faxes, documentos firmados), todo son imágenes, sin capa de texto, y el resultado será un texto vacío.

Hermes lo detecta de forma inteligente: si más del 20% de las páginas no producen texto (o más de 10 páginas en términos absolutos), añade una advertencia que muestra qué páginas están vacías y el último texto que apareció antes de ellas.

Por ejemplo:

[ADVERTENCIA DE COBERTURA DE EXTRACCIÓN: 198 de 311 páginas de este PDF no produjeron texto...
  páginas 42-77 (36 páginas) — después de "Antigua Maintenance Corp Bylaws" (p41)
  páginas 92-213 (122 páginas) — después de "... Covenants, Codes and Regulations" (p91)]

Dos formas de solucionarlo

Caso 1: Solo unas pocas páginas son escaneos — Usa renderizado + visión. Convierte esas páginas a imágenes:

pdftoppm -jpeg -r 150 -f 92 -l 94 document.pdf /tmp/page

Luego usa la herramienta vision_analyze para “mirar” las imágenes. Esto requiere que las herramientas poppler estén instaladas en tu sistema (que Hermes usa de todos modos para la detección).

Caso 2: La mayoría de las páginas son escaneos — Usa OCR para el reconocimiento por lotes. Hermes tiene una habilidad ocr-and-documents basada en marker-pdf, que admite más de 90 idiomas y maneja fórmulas y tablas. Necesita entre 3 y 5 GB de espacio en disco para instalarse.

Resumen

read_file permite que la IA lea casi cualquier formato de documento común, pero recuerda: un PDF necesita una capa de texto para leerse directamente. Consejo práctico: si trabajas habitualmente con escaneos, instala la habilidad de OCR de antemano. Si solo te encuentras con unas pocas páginas escaneadas de vez en cuando, usa pdftoppm para convertir a imágenes y el análisis por visión. No hagas que la IA haga OCR de un documento completo a ciegas: lee primero la advertencia, procesa solo las páginas realmente en blanco y ahorra tiempo y esfuerzo.