Manuale e Documentazione

🆕 Novità della versione 0.51-alpha

La 0.51 è una versione di consolidamento con una Dashboard tutta nuova: il motore è stato riscritto in moduli e ogni correzione è verificata da test ripetibili. Runtime, librerie e modelli IA sono gli stessi della 0.50 e funziona offline su Windows 11 appena installato.

• Nuova Dashboard per il lavoro in blocco: grafica più sobria; si aggiungono file o intere cartelle (anche con i pulsanti Seleziona file e Seleziona cartella), Apri cartella input e Apri cartella output aprono le cartelle in Esplora file e i contatori In attesa, Pronti e Non riusciti mostrano l'andamento del lotto. I documenti non elaborati sono elencati con il motivo e si rimettono in coda con un clic; l'elenco si esporta in CSV per Excel.
• Endpoint per gli agenti AI: in Modalità Avanzata la scheda Agenti AI e API mostra gli indirizzi del Proxy (formato OpenAI e formato Anthropic) e, per ogni strumento (Claude Code, Codex CLI, Cursor, Antigravity, Windsurf, OpenCode, Continue, Aider, SDK OpenAI e Anthropic), dove impostarli, con le istruzioni da copiare; seguono gli esempi delle API REST locali.
• Documenti Office intatti: Word, Excel, PowerPoint e OpenDocument vengono modificati direttamente nel loro XML. Grassetti, font, immagini, tabelle, formule e macro restano identici (la 0.50 cancellava formattazione e immagini dei DOCX). Vengono anonimizzati anche note a piè di pagina, caselle di testo, commenti e relativi autori, revisioni, note del relatore, grafici, metadati e miniature di anteprima.
• PDF più sicuri: OCR anche sulle scansioni con timbro di protocollo, oscuramento dei pixel sotto il testo delle scansioni "ricercabili", pagine ruotate gestite correttamente; anonimizzati campi modulo, commenti, segnalibri, metadati e allegati incorporati; le firme digitali PAdES (con nome e codice fiscale del firmatario) vengono rimosse.
• Proxy API corretto: nella 0.50 lo streaming per Claude Code e Codex (formati Anthropic e OpenAI Responses) non funzionava. Ora funziona, anche con immagini e PDF allegati; gli argomenti dei tool restano JSON validi e un'analisi a batch con cache rende le conversazioni lunghe molto più veloci.
• Nuovi formati: RTF nativo senza Word, file firmati .p7m (es. fattura.xml.p7m), JSON, TSV, Markdown, log, codice sorgente, GIF e modelli Office; i .doc/.xls che in realtà sono RTF, DOCX o HTML rinominati vengono riconosciuti senza Office.
• Riconoscimento più preciso: il modello italiano analizza i documenti lunghi per intero (prima si fermava dopo poche righe); RegEx validate per IBAN europei, codici fiscali (anche omocodici o letti male dall'OCR), carte di pagamento, telefoni, targhe e CIE; un nome trovato in un punto viene oscurato in tutto il documento.
• Affidabilità: il motore si chiude da solo con la finestra di Germano, i file vengono elaborati solo a copia completata, il Vault è protetto da scritture concorrenti, i documenti lunghi hanno fino a 60 minuti (configurabili) e la Dashboard mostra avanzamento e motivo di ogni errore.
• Sicurezza: l'API locale rifiuta le richieste provenienti da siti web esterni e il motore interno è protetto da token. Nessun dato dei documenti viene inviato in rete: l'unico collegamento automatico è il controllo degli aggiornamenti, solo quando Windows segnala che il PC è connesso a Internet.
• Per gli amministratori: blocco delle impostazioni per il profilo PA ("lock_settings": true), scelta della precisione del modello (FP32/BF16), anonimizzazione dei nomi dei file, servizio Anthropic configurabile a parte.
• Aggiornamenti automatici: solo quando Windows segnala che il PC è connesso a Internet, Germano controlla su GitHub se esiste una nuova versione, la scarica da Google Drive, ne verifica l'impronta SHA-256 e la installa al successivo avvio (o subito, con Installa ora e riavvia). Documenti, Vault e impostazioni non vengono toccati e, se l'installazione non va a buon fine, torna al suo posto la versione precedente. Si disattiva in Sistema e registro → Aggiornamenti o con "check_updates": false.

Aggiornare dalla versione 0.50

1. Chiudi Germano 0.50 ed estrai la 0.51 in una nuova cartella (non sovrascrivere la vecchia).
2. Per poter ancora ripristinare i dati veri nei documenti protetti con la 0.50, copia il file extracted/deanonymize_vault.json dalla vecchia cartella alla stessa posizione nella nuova.
3. Se vuoi conservare le impostazioni, copia anche config.json: i valori vengono controllati e completati automaticamente con le nuove opzioni.
4. Avvia START.bat dalla nuova cartella. Quando tutto funziona, puoi eliminare la cartella della 0.50.
5. Dalla 0.51 in poi non serve ripetere questi passaggi: Germano si aggiorna da solo quando il PC è connesso a Internet, conservando documenti, Vault e impostazioni.

L'elenco completo delle modifiche è nel CHANGELOG su GitHub.

1. Primi Passi (Modalità Semplice "A Prova di Errore")

Germano AI Standalone è stato progettato per essere completamente "Plug & Play": funziona al primo colpo su qualsiasi PC con Windows 11 appena formattato, senza richiedere connessione internet, né privilegi di amministratore, né installazioni preliminari di Python o driver.

1. Scarica l'archivio ZIP di Germano AI ed estrailo in una cartella a tua scelta (ad esempio sul Desktop o nei Documenti; meglio evitare percorsi molto lunghi).
2. Fai doppio clic sul file START.bat. Il server locale si avvierà all'istante e aprirà automaticamente la Dashboard nel tuo browser predefinito all'indirizzo http://127.0.0.1:8000.
3. Trascina documenti o intere cartelle nel riquadro «Trascina qui file o cartelle», oppure usa i pulsanti Seleziona file e Seleziona cartella. In alternativa copia i file nella cartella input: il pulsante Apri cartella input la apre in Esplora file. Per un testo breve usa il riquadro «Testo da inviare a un servizio di AI» e il pulsante Anonimizza testo.
4. Avvio del motore: se aggiungi documenti dalla Dashboard il motore si avvia da solo; se li hai copiati con Esplora file, clicca Avvia motore in alto (o Avvia elaborazione nell'avviso dei documenti in attesa). Il riquadro di stato mostra il documento in lavorazione e l'avanzamento del lotto, mentre i contatori In attesa, Pronti e Non riusciti si aggiornano in tempo reale.
5. I risultati compaiono nella tabella Documenti, scheda Pronti, con i pulsanti per aprirli, mostrarli nella cartella o scaricarne una copia; Apri cartella output apre l'intera cartella dei risultati. Nella scheda Non riusciti ogni documento riporta il motivo (es. PDF protetto da password) e il pulsante Rimetti in coda; Esporta elenco salva la tabella in formato CSV.

2. La Magia del Ripristino Automatico Dati (Nel Ritorno dall'AI)

Quando utilizzi ChatGPT, Claude, Gemini o un assistente di programmazione come Google Antigravity o Cursor per analizzare contratti o atti legali, finora sorgeva un problema noioso: se sostituisci "Mario Rossi" con [PERSONA_1], l'IA genererà una risposta parlando di [PERSONA_1], costringendoti a rimettere a mano tutti i dati veri.

Come Funziona il Flusso Senza Sforzo:

• Invia all'IA: Trascini il file o il testo in Germano. Germano produce la versione protetta con i tag univoci (es. [PERSONA_1], [INDIRIZZO_1]). Invii questo testo o documento all'IA in totale sicurezza GDPR.
• Elaborazione dell'IA: L'IA analizza o compila il documento mantenendo i tag assegnati.
• Ritorno Automatico: Scarica il documento prodotto dall'IA o incolla la risposta in Germano. Germano riconosce autonomamente che contiene etichette del Vault, riapre la cassaforte locale e rimette istantaneamente "Mario Rossi" e "Via Roma" al posto dei tag!

3. Guida alle 5 Cartelle di Lavoro Interne

Per garantire la massima sicurezza e la totale trasparenza, Germano AI lavora esclusivamente all'interno delle 5 cartelle del programma. Non accederà mai a cartelle esterne (nessun monitoraggio di Download o Desktop non autorizzati):

4. Modalità Avanzata & Le 18 Categorie Configurabili

Scegliendo Avanzata nel selettore in alto compaiono quattro schede: Elaborazione, Agenti AI e API, Filtri e modelli e Sistema e registro. In Filtri e modelli hai il controllo totale sui 6 modelli IA e su ciascuna delle 18 categorie di dati sensibili, che si attivano o disattivano singolarmente:

Profilo PA: tutte le categorie e tutti i modelli restano sempre attivi e la soglia IA è fissa allo 0%. Con "lock_settings": true in config.json l'amministratore impedisce qualsiasi modifica dalla Dashboard (compare un lucchetto 🔒 accanto al profilo).

5. I 6 Modelli IA Locali + Motore RegEx

Germano AI integra 6 reti neurali pre-installate nella cartella models/, funzionanti 100% offline, affiancate da un motore di regole deterministiche:

6. Formati Documentali Supportati

Germano AI supporta nativamente l'intero parco formati aziendale e della Pubblica Amministrazione, preservando impaginazione, font, immagini, formule e layout grafici originali:

• PDF & Scansioni (.pdf): censura a livello di singolo carattere con etichetta sostitutiva; OCR e oscuramento dei pixel su scansioni, scansioni con timbro di protocollo, scansioni "ricercabili" e pagine ruotate; anonimizzazione di campi modulo, commenti, segnalibri, metadati e allegati incorporati; le firme digitali PAdES vengono rimosse.
• Microsoft Word (.docx, .docm, .dotx, .rtf): modifica diretta dell'XML, con formattazione, immagini e campi intatti. Coperti tabelle (anche annidate), intestazioni, piè di pagina, note, caselle di testo, commenti, revisioni e metadati; RTF elaborato nativamente, senza Word.
• Microsoft Excel (.xlsx, .xlsm, .xls, .csv, .tsv): celle, commenti, grafici e nomi dei fogli (le formule vengono aggiornate al nuovo nome), con stili, formule e macro VBA preservati.
• PowerPoint (.pptx, .pptm, .ppsx): testi, forme raggruppate, tabelle, SmartArt, grafici, note del relatore, commenti e immagini delle slide.
• Vecchi formati Office (.doc, .ppt): se il file è in realtà RTF, DOCX o HTML rinominato viene elaborato direttamente; i veri file binari richiedono Microsoft Office o LibreOffice installato.
• Web & Fatture Elettroniche (.html, .htm, .xml): struttura preservata; analizzati testo, commenti e attributi (title, alt, mailto:, metadati). I campi FatturaPA (Nome, Cognome, CodiceFiscale, Indirizzo...) sono riconosciuti automaticamente.
• File firmati digitalmente (.p7m, CAdES): es. fattura.xml.p7m; il documento interno viene estratto e anonimizzato e in uscita si ottiene il documento senza firma (che conterrebbe nome e codice fiscale del firmatario).
• Posta Elettronica (.eml): mittente, destinatari, oggetto, intestazioni, corpo testo/HTML, messaggi inoltrati e allegati (elaborati col proprio formato; quelli non elaborabili vengono sostituiti da un avviso).
• OpenDocument (.odt, .ods, .odp): testo, intestazioni e piè di pagina, note, commenti, metadati e immagini; la miniatura di anteprima viene sostituita.
• Fotografie e scansioni (.png, .jpg, .jpeg, .bmp, .webp, .tiff, .gif): OCR con oscuramento delle sole parti personali, di volti, firme e targhe; risoluzione originale e TIFF multipagina preservati, orientamento corretto, metadati EXIF/GPS rimossi.
• Testo e dati (.txt, .json, .jsonl, .md, .log, codice sorgente): codifica originale preservata (UTF-8, UTF-16, ANSI: le lettere accentate non vanno perse).
• Archivi Compressi (.zip): ogni file interno (anche ZIP annidati) viene elaborato col proprio formato; per sicurezza i file non anonimizzabili (es. eseguibili o protetti da password) non vengono copiati nell'archivio in uscita e sono elencati nel report di audit.

7. Specifiche API REST Complete

Germano AI espone una suite di API REST HTTP sincrone all'indirizzo http://127.0.0.1:8000 per l'integrazione con gestionali, CRM, portali web o script di automazione aziendale:

1. Anonimizzazione Testo (POST /api/v1/anonymize_text)

Restituisce il testo anonimizzato (anonymized) e l'elenco delle entità (extracted_data: parola, etichetta, categoria, punteggio). Se il testo contiene etichette del Vault e lo switch di ripristino è attivo, viene invece restituito con i dati veri e "auto_restored": true; con "force_anonymize": true si anonimizza sempre.

2. De-Anonimizzazione Testo (POST /api/v1/deanonymize_text)

3. Anonimizzazione File Singolo (POST /api/v1/anonymize)

Restituisce il file anonimizzato nel formato originale (per i .p7m il documento interno), a elaborazione completata anche per i documenti lunghi; il report di audit viene salvato in extracted/api/. Se il file contiene etichette del Vault viene invece restituito con i dati veri. Errori: 400 nessun file, 415 formato non supportato, 503 motore non avviato.

4. Stato e Telemetria (GET /api/status)

Restituisce lo stato operativo (running, loading_models, stopped, oppure error con il relativo messaggio), il conteggio dei file nelle cartelle, l'avanzamento del documento in lavorazione, il profilo attivo e l'utilizzo di CPU e RAM.

5. Ripristino Dati Veri in un File (POST /api/v1/deanonymize_file)

Rimette i dati veri al posto delle etichette del Vault in uno o più file restituiti dall'AI (campo files o file), senza usare il motore IA. I file ripristinati vengono salvati in output/ con il prefisso ripristinato_; con ?raw=1 e un solo file la risposta è direttamente il file.

8. Proxy Trasparente per Agenti IA & Coding Tools

Germano AI include un Proxy API Bidirezionale Intelligente compatibile con le specifiche OpenAI (/v1/chat/completions), Anthropic (/v1/messages) e OpenAI Responses (/v1/responses).

Streaming SSE e Chiamate Funzione (tool_calls)

Il parser SSE conforme alle specifiche fa funzionare lo streaming con Claude Code (Anthropic) e Codex (OpenAI Responses). Le etichette spezzate tra più frammenti (es. [PER + SONA_1]) vengono ricomposte ed emesse con il dato vero in tempo reale, con un buffer separato per ogni blocco. Quando gli agenti invocano strumenti di scrittura file (write_file, edit_file), Germano de-anonimizza gli argomenti JSON con l'escape corretto: i file salvati sul tuo computer contengono sempre i dati reali.

Cosa viene anonimizzato e cosa viene bloccato

• Anonimizzati: messaggi, istruzioni di sistema, argomenti e risultati dei tool, riassunti del ragionamento, immagini e documenti allegati (PDF, Word, Excel, testo) nei formati OpenAI, Responses e Anthropic.
• Lasciati intatti: i blocchi thinking firmati di Claude (generati dall'AI a partire da testo già anonimo: una modifica invaliderebbe la firma), le definizioni dei tool e i parametri tecnici.
• Bloccati (fail-safe): audio (la voce è un dato biometrico) e allegati di formato sconosciuto; se il motore IA non è attivo la richiesta non viene inoltrata.
• Sono inoltrati gli header necessari (Authorization, x-api-key, anthropic-version, anthropic-beta...) e i parametri dell'indirizzo; è supportato anche /v1/messages/count_tokens. Le connessioni usano il proxy di sistema e i certificati di Windows (reti aziendali con ispezione TLS).
• La mappa delle sostituzioni di ogni richiesta viene registrata in extracted/proxy_sessions/AAAA-MM-GG.jsonl (disattivabile con "save_proxy_logs": false in config.json).

Configurazione Passo-Passo per ogni Strumento:

• Claude Code: Imposta $env:ANTHROPIC_BASE_URL = "http://127.0.0.1:8000" (senza /v1) prima di lanciare claude. Le richieste vengono inoltrate al servizio indicato nella scheda Agenti AI e API, campo «Servizio Anthropic (Claude)» (predefinito https://api.anthropic.com/v1).
• OpenAI Codex CLI: Imposta nel terminale PowerShell $env:OPENAI_BASE_URL = "http://127.0.0.1:8000/v1" prima di lanciare codex.
• Cursor IDE: In Impostazioni -> Models inserisci la tua vera API key e, in Override OpenAI Base URL, http://127.0.0.1:8000/v1.
• Google Antigravity: Configura l'endpoint di base nelle impostazioni di rete su http://127.0.0.1:8000/v1.
• Windsurf IDE: Configura l'OpenAI Endpoint su http://127.0.0.1:8000/v1.

Il servizio a cui Germano inoltra le richieste OpenAI-compatibili si imposta nella scheda Agenti AI e API, campo «Servizio OpenAI o compatibile» (predefinito https://api.openai.com/v1/chat/completions); la stessa scheda elenca, strumento per strumento, l'indirizzo da impostare. La tua API key resta quella vera: Germano la usa solo per inoltrare la richiesta già anonimizzata.

Prestazioni: la prima richiesta di una conversazione lunga può richiedere alcune decine di secondi su CPU; i messaggi già analizzati vengono memorizzati, quindi le richieste successive analizzano solo il testo nuovo.

9. Architettura & Tecnologie

Dietro le quinte, Germano AI orchestra i migliori componenti Open Source di classe enterprise:

• Python 3.11 Embedded: Runtime portatile isolato con 12 DLL Microsoft Visual C++ integrate (zero-admin).
• PyTorch 2.14 & HuggingFace Transformers 5.20: Motore di inferenza locale su CPU (precisione FP32 o BF16 automatica) e, con la versione CUDA di PyTorch, su GPU NVIDIA.
• PyMuPDF 2.0: Censura a livello di carattere, OCR delle scansioni e oscuramento dei pixel nei documenti PDF.
• lxml: Modifica diretta dell'XML di Word, Excel, PowerPoint e OpenDocument senza alterare la formattazione.
• OpenCV 5.0 Headless & YOLOS: Visione artificiale per il rilevamento di volti (YuNet DNN), firme autografe e targhe.
• Flask / Werkzeug: Dashboard, API REST e Proxy in ascolto solo su 127.0.0.1, protetti contro DNS-rebinding e CSRF.

10. Requisiti Hardware & Standalone su Windows 11 Vanilla

Germano AI è ottimizzato per funzionare su una vasta gamma di configurazioni:

• Requisiti Minimi: Windows 10/11 (64-bit), CPU Intel Core i5 / AMD Ryzen 5, 8 GB RAM, 6 GB spazio su disco.
• Requisiti Consigliati: Windows 11 (64-bit), 16 GB di RAM, disco SSD. La scheda video non è necessaria: il pacchetto usa PyTorch per CPU; l'accelerazione NVIDIA (CUDA) richiede di sostituire PyTorch con la versione CUDA.
• Memoria e precisione: con almeno 12 GB di RAM il modello principale viene caricato in FP32 (circa 5,5 GB, veloce), con meno di 12 GB in BF16 (circa 2,8 GB, più lento sui processori meno recenti). La scelta si può forzare in Modalità Avanzata.
• Windows 11 appena installato: nessuna installazione, nessun privilegio di amministratore e nessun download: runtime Python, librerie Visual C++ e modelli sono già inclusi. Se Smart App Control o l'antivirus bloccano i componenti, START.bat lo segnala all'avvio.

11. Dati di Addestramento & Privacy by Design

I modelli linguistici e visuali inclusi in Germano sono stati addestrati su corpora pubblici e dataset sintetici generati matematicamente (come PII-Masking-300k, SynthText e ICDAR). Questo garantisce che i modelli non abbiano mai memorizzato dati personali di individui reali, assicurando la totale conformità al principio di Privacy by Design (Art. 25 GDPR).

12. Domande Frequenti (FAQ) & Risoluzione Errori

D: Germano AI invia qualcosa su Internet?

R: Nessun dato dei documenti. L'anonimizzazione di documenti e testi avviene interamente sul PC: i 6 modelli IA risiedono nella cartella models/ e la telemetria delle librerie è disattivata. Le sole connessioni sono il controllo degli aggiornamenti, solo se Windows segnala che il PC è connesso a Internet (legge da GitHub il numero dell'ultima versione e, se serve, scarica il pacchetto da Google Drive; si disattiva in Sistema e registro → Aggiornamenti o con "check_updates": false), e il Proxy API, solo se lo usi, che inoltra all'AI scelta da te le richieste già anonimizzate.

D: I documenti Word, Excel e PowerPoint mantengono formattazione e formule?

R: Sì. Word, Excel, PowerPoint e OpenDocument vengono modificati direttamente nel loro XML: formattazione, immagini, tabelle, formule e macro VBA restano intatte e cambia solo il testo personale. Nei PDF le etichette vengono inserite al posto del testo rimosso, con un corpo ridotto se lo spazio è stretto.

D: Il motore non parte o compare un messaggio rosso di errore

R: Il messaggio in alto nella Dashboard indica la causa; il dettaglio completo è nel file daemon.log nella cartella del programma. Su alcuni PC appena installati Smart App Control o l'antivirus possono bloccare i componenti IA: START.bat lo segnala all'avvio. Evita anche percorsi molto lunghi (meglio C:\GermanoAI).

D: Cosa succede se la porta 8000 è occupata?

R: Se Germano è già aperto, un nuovo doppio clic su START.bat apre semplicemente la Dashboard esistente. Se la porta è usata da un altro programma, chiudilo oppure imposta un'altra porta in config.json (es. "port": 8010) e aggiorna l'indirizzo del Proxy negli editor.

D: Perché vedo l'avviso «Sono rimasti aperti ... processi del motore»?

R: Il motore IA si chiude da solo quando chiudi la finestra di Germano; l'avviso (visibile in Modalità Avanzata) può comparire solo dopo un arresto anomalo del PC. Basta cliccare «Chiudi processi secondari» nell'avviso in cima alla pagina.

D: Perché un file .doc o .ppt finisce tra i «Non riusciti»?

R: I vecchi formati binari di Office si possono convertire solo con Microsoft Office o LibreOffice installati. Su un PC senza Office salva il documento come .docx/.pptx, oppure installa LibreOffice: Germano lo usa automaticamente. Il motivo esatto di ogni errore è indicato nella scheda Non riusciti; risolto il problema, usa Rimetti in coda.

D: Come impedisco agli operatori di disattivare i filtri (Profilo PA)?

R: L'amministratore imposta in config.json i valori "compliance_mode": "PA" e "lock_settings": true: la Dashboard mostra il lucchetto 🔒 accanto al profilo e rifiuta ogni modifica dei filtri (resta possibile solo il passaggio tra Modalità Semplice e Avanzata).

D: Ho la versione 0.50: come passo alla 0.51 senza perdere nulla?

R: Estrai la 0.51 in una nuova cartella e copia dalla vecchia extracted/deanonymize_vault.json (serve per ripristinare i dati veri nei documenti già protetti) e, se vuoi, config.json con le tue impostazioni. I dettagli sono nella sezione Novità della v0.51.

D: Come funzionano gli aggiornamenti automatici?

R: Circa 20 secondi dopo l'avvio e poi ogni 6 ore, solo se Windows segnala che il PC è connesso a Internet, Germano legge da GitHub il file update.json con il numero dell'ultima versione. Se è più recente, scarica il pacchetto da Google Drive nella cartella update/, ne verifica dimensione e impronta SHA-256 e lo prepara; l'installazione avviene al successivo avvio di START.bat oppure subito con Installa ora e riavvia. Cartelle di lavoro, Vault e config.json non vengono toccati; se l'installazione non va a buon fine torna al suo posto la versione precedente. Su un PC scollegato non avviene alcun tentativo di connessione. Per disattivare il controllo: Sistema e registro → Aggiornamenti oppure "check_updates": false in config.json; con "auto_update": false Germano si limita a segnalare la nuova versione.