Estrazione di Documenti — Dalla Scansione al Testo

Immagina di consegnare un contratto a un collega, e lui lo sfoglia dicendo: “Sono tutte immagini, non riesco a leggere una parola.” È esattamente il problema che risolviamo oggi. Lo strumento read_file di Hermes Agent ora può “aprire” i file come farebbe un umano — trasformando PDF, documenti Word, fogli Excel e persino vecchi file Office in testo semplice che può davvero capire.

Tre Formati, Zero Configurazione

I formati più comuni funzionano subito, senza bisogno di installare nulla:

Notebook Jupyter (.ipynb)
Documenti Word (.docx)
Fogli di calcolo Excel (.xlsx)

Questi vengono convertiti in testo Markdown e supportano la lettura paginata tramite i parametri offset e limit — proprio come sfogliare un libro, pagina per pagina.

Tutto il Resto: Auto-Installato, Nessuna Preoccupazione

Per PDF, vecchi file Office (.doc, .ppt, .xls), OpenDocument ed ebook (.epub), Hermes installa automaticamente un convertitore chiamato firecrawl-anydoc al primo utilizzo. Non devi muovere un dito.

Un’avvertenza: se la configurazione di sistema disabilita l’auto-installazione (security.allow_lazy_installs impostato su false), funzionano solo i tre formati integrati — tutto il resto viene trattato come binario. Inoltre, i file oltre i 50MB vengono rifiutati per evitare tempi di elaborazione eccessivamente lunghi.

Funziona Anche in Ambienti Remoti

Che il tuo codice giri su Docker, Modal o un server remoto SSH, i file vengono automaticamente trasferiti alla tua macchina locale per la conversione. Leggere un documento in una sandbox funziona esattamente come leggerlo localmente.

Il Grande Avvertimento: Le Scansioni Sono “PDF Finti”

Ecco la trappola: la conversione PDF legge solo il livello di testo. Se un PDF è una scansione (contratti cartacei, fax, documenti firmati), è tutto immagini — nessun livello di testo — e il risultato è vuoto.

Hermes lo rileva intelligentemente: se più del 20% delle pagine non produce testo (o più di 10 pagine in assoluto), antepone un avviso che mostra quali pagine sono vuote e l’ultimo testo apparso prima di esse.

Per esempio:

[AVVISO DI COPERTURA ESTRAZIONE: 198 di 311 pagine in questo PDF non hanno prodotto testo...
  pagine 42-77 (36 pagine) — dopo "Antigua Maintenance Corp Bylaws" (p41)
  pagine 92-213 (122 pagine) — dopo "... Covenants, Codes and Regulations" (p91)]

Due Modi per Risolvere

Caso 1: Solo poche pagine sono scansioni — Usa rendering + visione. Converti quelle pagine in immagini:

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

Poi usa lo strumento vision_analyze per “guardare” le immagini. Questo richiede che gli strumenti poppler siano installati sul tuo sistema (che Hermes usa comunque per il rilevamento).

Caso 2: La maggior parte delle pagine sono scansioni — Usa l’OCR per il riconoscimento batch. Hermes ha una skill ocr-and-documents basata su marker-pdf, che supporta oltre 90 lingue e gestisce formule e tabelle. Servono 3–5GB di spazio su disco per installarla.

Riepilogo

read_file permette all’AI di leggere quasi ogni formato di documento comune — ma ricorda: un PDF deve avere un livello di testo per essere letto direttamente. Consiglio pratico: se gestisci regolarmente scansioni, installa subito la skill OCR. Se ti capita solo qualche pagina scansionata di tanto in tanto, usa pdftoppm per convertire le immagini + analisi visiva. Non far fare all’AI un OCR cieco dell’intero documento — leggi prima l’avviso, elabora solo le pagine davvero vuote e risparmia tempo e fatica.