gtagger (0.1.5)
Installation
pip install --index-url About this package
convert documents and implement semantic search
gtagger
flowchart TD
A[Documento in ingresso] --> A1(Estrazione dati)
A1[Conversione MardDown] --> B(Estrazione dati)
B --> C[Caricamento su Paperless]
C --> D{Risultato}
D -->|Successo| E[Invio Campi personalizzati]
D -->|Fallimento| F[Log errori]
Input e Requisiti
Tipi di File Supportati
| Formato | Note |
|---|---|
| Testo nativo o OCR (Tesseract) | |
| doc | Estrazione testo strutturato (Tika) |
| pptx | Estrazione testo strutturato (MarkItDown) |
| xlxs,docx,odt | Estrazione testo strutturato (MarkItDown o Tika) |
Metadati Estratti
Titolo: Nome del file senza estensione
Data Creazione: data ricavata dal nome del file (se possibile) o dalla data di ultima modifica dello stesso Corrispondenti: il nome dell'evento (Es. FIERACAVALLI, MOTORBIKE) estratto dal nome della prima directory dell'archivio Tipo di documento: dedotto dall'analisi del contenuto Persone Citate: elenco delle persone citate nel documento (Nome Cognome) Argomenti: elenco dei principali argomenti del documento, dedotto dall'analisi del contenuto Anno: tag dell'anno a cui si riferisce l'evento Tipo di evento: codifica dell'evento fieristico Relatori: eventuali persone che forniscono dichiarazioni Persone Evidenziate: Persone citate nel documento che appartengono ad un elenco di persone selezionate. Nome File: nome del file costruito seguendo regole fissate.
Operatività
Le operazioni effettuabili sull'archivio sono distinte in conversione del testo (convert), analisi del testo (evaluate), caricamento su Paperless-ngx (upload).
E' fornito lo strumento per un report dei risultati ottenuti (report) e il popolamento dei principali metadati su Paperless-ngx (setup), utile in caso di sviluppo, per evitare di inserirli tutti a mano.
L'operazione di conversione prevede l'uso di applicativi come Apache Tika e MarkitDown. Tika è lo strumento predefinito, perché è quello usato da Paperless, tuttavia non è in grado di convertire il formato pptx, che quindi è dato in pasto a Markitdown. A sua volta, anche quest'ultimo ha le sue limitazioni: non converte il vecchio formato doc di Word. La conversione è la prima operazione da effettuare, e genera dei files markdown nello stesso path dell'originale. Se un file è già presente l'operazione di conversione non viene effettuata. I files pdf generati da scansione vengono sottoposto a un'operazione di OCR preliminare. Se nella directory, per uno stesso file è presente più di un formato, tipicamente l'originale più la stampa pdf, viene preso l'originale e il pdf non viene considerato.
L'operazione di analisi avviene sottoponendo il file markdown all'AI. Quindi se un documento non ha il suo corrisponente mmarkdown, non verrà analizzato. Per questo è necessaria l'operazione di conversione. Il risultato dell'analisi è memorizzato in un file .json, a fianco dell'originale. Se per un file è già presente il file json, l'operazion di analisi non è effettuata.
L'upload a Paperless-ngx avviene per i documenti che hanno subito l'analisi e quindi sono associati ad un file .json. Prima viene inviato l'originale, successivamente sono aggiunti i Campi Personalizzati.
Uso
$ gtagger
usage: gtagger [-h] [-c CONFIG] [--config-save CONFIG_SAVE] [--debug] [--dry-run] [--task {upload,report,evaluate,convert,setup}] [--model MODEL] [--env {development,production}] [-e EXTENSION]
[--log-file LOG_FILE] [--paperless PAPERLESS] -t TOKEN
[files ...]
-c CONFIG percorso di un file di configurazione yaml. Generabile con l'opzione [--config-save CONFIG_SAVE].
--task {upload,report,evaluate,convert,setup} l'operazione da effettuare sull'archivio
files la radice dell'archivio. Notare che è vincolante scegliere la corretta radice, perché alcune informazioni sono estratte dal nome della prima sottodirectory.
--model MODEL Modello differente da quello di default ("gemini-2.0-flash-lite-001")
--env {development,production} Default: ("development") è importante soprattutto per il motore AI usato
--debug aumenta la verbosità dei log
-t TOKEN per mette di passare un token di paperless-ngx all'applicazione. Utile con il fla --paperless
--paperless PAPERLESS consente di specificare un url base di Paperless-ngx, utile in modo sviluppo per un server locale (Es. http://localhost:8080)
--log-file LOG_FILE è disponibile solo quando si usa --debug, e salva una copia dei log su file.
Installation
editable mode for development
uv pip install -e .
#uv sync --active
Conversione documenti
I documenti sono convertiti in testo (e salvati con estensione <*.md>) usando 3 diversi motori di conversione:
- markdown
- ocr
- tika
task start # nella radice del progetto paperless
gtagger -c gtagger.yaml --task convert ./samples/"**"
Elaborazione AI
Per lo sviluppo generare una chiave in https://aistudio.google.com/apikey
export GOOGLE_API_KEY=chiave_API gtagger -c gtagger.yaml --task ai ./samples/"**"
Upload
In ambiente di sviluppo puntare al proprio paperless backend ("--paperless") usando il token (richiesto in admin -> profile -> API auth token) o usare un file di configurazione adattato per l'ambiente locale
export PAPER_TOKEN=...
# solo la prima volta per creare i tags, custom fields, etc
gtagger -c gtagger.yaml --task setup --token $PAPER_TOKEN --debug --paperless "http://localhost:8000"
# upload
gtagger -c gtagger.yaml --task upload --token $PAPER_TOKEN --paperless "http://localhost:8000" ./samples/"**"
Semantic Search
# initialize database
rm -fR ./runtime
# add documents to the database
nlsearch samples/REPORT\ RIUNIONE\ COMUNICAZIONE\ VINITALY\ 14.02.md
nlsearch "samples/*.md"
# search for a query in the database
nlsearch --query "sindaco di verona"