Come usare la ricerca scientifica CLINTELITALIA

Indice

Cos’è il motore RAG

Il motore di ricerca CLINTELITALIA ti permette di fare domande in italiano su documenti scientifici e tecnici raccolti nel progetto. Il sistema non «inventa» a caso: prima recupera passaggi pertinenti dalla base documentale, poi li sintetizza in una risposta con rimandi alle fonti (approccio RAG).

Dalla pagina di presentazione

Sul sito CLINTELITALIA la presentazione ufficiale è la pagina del menu Approfondimenti AI RAG per l'analisi critica del clima. Da lì il pulsante «PROSEGUI…» apre la pagina operativa Ricerche CLINTEL.

Non serve installare programmi: basta un browser aggiornato. Dal link «← Introduzione» in alto nella pagina Ricerche torni sempre alla presentazione sul sito.

Pagina Ricerche CLINTEL (gorag.html)

In alto trovi i collegamenti principali:

• ← Introduzione — pagina di presentazione sul sito CLINTELITALIA.
• Portale — home del sito.
• Accesso area riservata — login per salvare sul server CLINTEL (credenziali NAS).
• Guida all’utilizzo del RAG / Guida rapida — questa guida e un riepilogo a comparsa.

Nella barra di navigazione sotto:

• Archivio ricerche — elenco di ciò che hai salvato (server e dispositivo).
• Archivio grafi — catalogo delle mappe (dopo averne aperte almeno una).
• Configurazione RAG — solo per chi gestisce il sistema (password tecnica diversa dall’area riservata).

Al centro: il riquadro della domanda, il pulsante «Cerca →», e più sotto le opzioni (numero fonti, lingua, memoria conversazione…). Al primo utilizzo puoi lasciare i valori predefiniti.

Scrivere e cercare

• Scrivi una frase intera, come a un collega: «Quali critiche alla teoria X compaiono negli studi indicizzati?»
• Il secondo riquadro «per la mappa» è facoltativo: serve solo se vuoi un titolo o un angolo diverso per la mappa rispetto alla domanda principale.
• «Azzera campi e memoria» cancella testo e memoria breve della sessione: utile per ripartire da zero.
• La casella memoria / conversazione, se attiva, fa tenere conto alle domande successive degli scambi recenti nella stessa pagina.

Leggere i risultati

Dopo «Cerca» resti sulla stessa pagina. Può comparire un avanzamento (percentuale o messaggio di attesa): è normale.

• Risposta principale — testo da leggere con attenzione.
• Fonti e documenti — link, anteprima o scarico dei file usati dal motore.
• Interrompi — ferma la richiesta in corso se hai sbagliato domanda.
• Strisce rosse o gialle — spesso indicano che il collegamento con il motore sul PC/server non è raggiungibile; riprova più tardi o segnala a chi gestisce il sistema.

Salvare: due modi diversi

In fondo alla pagina Ricerche ci sono due gruppi di pulsanti. Non sono equivalenti: conviene capire dove finiscono i dati.

1 — Sul server CLINTEL (area riservata)

• Salva solo ricerca — memorizza domanda e risultati nell’archivio server. Richiede accesso area riservata attivo.
• Salva ricerca + mappa — avvia anche la creazione della mappa, poi completa il salvataggio sul server dopo «Salva mappa» nel catalogo (vedi sotto).

Questi salvataggi sono legati al tuo account sul server NAS del progetto e compaiono in Archivio ricerche → sezione server.

2 — Sul dispositivo (file JSON)

• Salva ricerca su file — scarica un file JSON sul tuo computer/tablet e aggiorna l’elenco locale in Archivio ricerche.
• Salva ricerca + grafo su file — come sopra, con riferimento alla mappa se ne hai già una aperta in questa sessione.
• Carica ricerca da file — ripristina in pagina una ricerca salvata in precedenza.

Accesso area riservata

Il pulsante «Accesso area riservata» in alto apre il login con username e password gestiti sul server NAS del progetto (non è la password della «Configurazione RAG» tecnica).

• Serve per salvare ricerche sul server e per registrare mappe nel catalogo condiviso.
• Dopo il login compare «Esci (nome utente)».
• Se inserisci troppe volte password errate, l’accesso si blocca per alcuni minuti: attendi o chiedi a chi gestisce gli utenti di sbloccare.
• La sessione scade dopo alcune ore: se un salvataggio server fallisce, accedi di nuovo.

Archivio ricerche

La pagina Archivio ricerche (link in navigazione) ha due sezioni:

Archivio sul server CLINTEL

• Elenco delle ricerche salvate con area riservata attiva.
• Per aprire una voce serve essere di nuovo autenticati.
• L’elenco può restare visibile anche dopo «Esci», come promemoria dell’ultimo aggiornamento in questo browser.

Archivio su questo dispositivo

• Voci salvate localmente o importate da file JSON.
• Restano legate a questo browser: altro PC o cancellazione dati del sito possono farle sparire.
• Puoi importare un file JSON di backup dalla stessa pagina.

Cliccando «Apri» su una voce, torni a Ricerche con domanda e risultati ripristinati. Se la voce aveva una mappa collegata, compare una striscia con il link per riaprirla.

Mappe dei concetti (grafo)

Oltre al testo, puoi ottenere una mappa visiva: nodi (concetti) collegati da archi (relazioni). È lo strumento mappe CLINTEL integrato nel flusso Ricerche — la stessa infrastruttura usata dal progetto per esplorare e salvare i temi emersi dalla ricerca.

• «Grafo APPRENDO →» (sotto i risultati) — crea la mappa dalla domanda corrente; si apre in una nuova scheda con schermata di attesa, poi l’editor della mappa.
• La mappa non sostituisce la risposta testuale: la integra con una vista diversa.
• Nell’editor puoi trascinare la vista, zoomare con la rotellina, spostare i nodi e aprire la scheda di ogni concetto con un clic sul nodo.
• In alto trovi la barra comandi (layout, modifica, hover, ricerca globale…): vedi la sezione dedicata sotto.
• A destra c’è il pannello laterale con le schede Scheda, Info, Lista e Testo: anche questa ha una sezione dedicata sotto.

Barra comandi dell’editor mappa

Nella fascia in alto dell’editor (sotto il titolo della mappa) trovi i comandi principali. Molti restano memorizzati nel browser (layout, aspetto grafo, tema chiaro/scuro).

Pannello laterale destro

Il pannello a destra ha quattro schede in alto. Ogni scheda ha uno slider della dimensione testo (A ─── A) indipendente: utile su schermi grandi o per chi preferisce caratteri più grandi.

Scheda — dettaglio del nodo selezionato

Clicca un nodo sul canvas per aprire la sua scheda. Qui trovi:

• Definizione, ruolo, note, prerequisiti, applicazioni — testo strutturato del concetto.
• Relazioni — collegamenti in uscita e in entrata; i nomi sono cliccabili per saltare ad altri nodi.
• Collassa / Espandi ramo — nasconde o mostra i discendenti del nodo sul canvas (doppio clic sul nodo fa la stessa cosa).
• Espandi nodo con AI — genera nuovi concetti collegati; poi scegli se aggiungerli alla mappa corrente (subito visibili, salva dopo con «Salva mappa») o creare un grafo collegato separato.
• Modalità capitolo — influenza approfondimento, espansione e generazione capitolo: Auto (il sistema sceglie), Matematica (formule e notazione rigorosa), Critica (analisi argomentativa).
• Livello estensione / profondità (slider 1–5) — vale per tutte le richieste AI in questa scheda: più alto = risposta più lunga e approfondita, ma tempi maggiori. Livelli 4–5 possono richiedere diversi minuti.
• Istruzioni aggiuntive (opzionale) — testo libero per orientare l’AI (es. «non usare il consenso come argomento»).
• Corpus CLINTEL (casella) — per capitoli e approfondimenti: oltre al frammento del nodo, interroga l’indice documentale CLINTEL per altre fonti correlate.
• Approfondisci con AI — testo breve nella scheda stessa (non apre pannello fluttuante).
• Genera capitolo completo — crea un pannello fluttuante sul canvas con un capitolo esteso (markdown, formule, export HTML/Markdown). Il contenuto può essere salvato sul nodo e riaperto alla prossima visita (compare il bordo viola sul nodo e il pulsante Indice in alto).
• Approfondisci sezione da file — carica un file (PDF, testo…) e analizza una sezione collegata al nodo in un pannello dedicato.
• Apri grafo collegato — se il nodo ha un’espansione salvata come mappa figlia, link per aprirla in un’altra scheda (Ctrl+clic sul nodo sul canvas fa lo stesso).

Info — riepilogo della mappa

• Sommario e statistiche (numero nodi e relazioni).
• Legenda colori — principale, interno, esterno, riferimento, espansione (nodi aggiunti con AI).
• Comandi rapidi: Adatta grafo, Espandi tutto, Contrai tutto, Solo nodi principali, export .mm, Rinomina, Elimina grafo.

Lista — elenco di tutti i nodi

Nodi raggruppati per tipo (principale, interno, esterno, riferimento, espansione). Clic su una voce → seleziona il nodo sul canvas e apre la scheda.

Testo — aggiungi concetti da appunti

• Incolla appunti, paragrafi o spiegazioni nell’area di testo (almeno qualche riga).
• Estrai concetti e aggiungi al grafo — l’AI (anche locale con Ollama, se configurato) estrae nodi e relazioni e li inserisce nella mappa.
• I nuovi concetti compaiono subito sul canvas; usa Salva mappa per registrarli definitivamente.
• Dopo l’estrazione compare l’anteprima dei concetti aggiunti e il provider usato.

Salva ricerca + mappa (flusso completo)

Se vuoi ricerca e mappa sul server, il percorso consigliato è:

1. Esegui la ricerca e leggi i risultati.
2. Accedi all’area riservata se non lo sei già.
3. Premi «Salva ricerca + mappa».
4. Attendi l’apertura della mappa; quando è pronta, usa «Salva mappa» in alto nell’editor per registrarla nel catalogo (ti verrà chiesto un nome).
5. Torna a Ricerche: la ricerca viene completata nell’archivio server con il collegamento alla mappa.

Se interrompi prima di «Salva mappa», la ricerca può restare senza mappa definitiva nel catalogo: puoi riprovare o salvare solo la ricerca.

Modificare una mappa

Nell’editor, il pulsante «Modifica» (barra in alto) attiva la modalità di editing sul canvas:

• Tasto destro su area vuota → aggiungi un nodo (scegli etichetta e tipo).
• Primo clic su un nodo, poi secondo clic su un altro → crea un arco (scegli il tipo di relazione).
• Clic su un arco in modalità modifica → elimina l’arco (con conferma).
• Menu contestuale (tasto destro sul nodo) → elimina nodo, evidenzia, apri grafo collegato, ecc.
• Le modifiche restano solo in memoria finché non premi «Salva mappa» (catalogo server con area riservata, oppure file JSON sul dispositivo).

Puoi anche arricchire la mappa dalla scheda Testo (estrazione da appunti) o con Espandi nodo con AI nella scheda del nodo — stessa regola: visibili subito, salvataggio definitivo con «Salva mappa». Ctrl+clic su un nodo con grafo figlio apre l’espansione collegata. Se esci con modifiche non salvate, il browser può chiedere conferma.

Vedi anche: barra comandi e pannello laterale.

Archivio mappe

• Archivio grafi (da navigazione Ricerche) — catalogo delle mappe salvate nel progetto; da lì ne riapri una esistente.
• Mappe salvate solo su dispositivo compaiono in una cartella dedicata nell’archivio mappe.
• Alcune installazioni offrono ricerca testuale tra tutte le mappe del catalogo.

Archivio ricerche e Archivio mappe sono due elenchi diversi: il primo riguarda le domande e i risultati; il secondo le mappe come documenti a sé.

Messaggi e problemi comuni

• Motore non raggiungibile — il PC che ospita il RAG o il tunnel verso il sito non è attivo; riprova o contatta chi gestisce il sistema.
• Area riservata / troppi tentativi — password errate ripetute: attendi il tempo indicato o chiedi lo sblocco.
• Sessione scaduta — accedi di nuovo all’area riservata prima di salvare sul server.
• Rate limit / quota API — messaggi su limiti del provider AI: di solito temporanei; riprova o segnala agli amministratori.
• Grafo non corrisponde alla ricerca — riapri la mappa dal flusso «Salva ricerca + mappa» o rigenera da Ricerche.
• Checkbox memoria — disattivala o usa «Azzera» se vuoi domande indipendenti.

Telefono, tablet e schermo piccolo

Su schermi stretti (circa fino a 680px) puoi cercare, usare Salva ricerca su file e aprire Archivio ricerche. I pulsanti per generare mappe e «Salva ricerca + mappa» sono nascosti perché la mappa sarebbe illeggibile: usa tablet in orizzontale o PC.

Tablet (mappe e pannelli)

• Orizzontale consigliato — più spazio per canvas e pannelli capitolo fluttuanti.
• Trascinare un pannello — usa la barra colorata in alto (icona ⋮ accanto al titolo) oppure i bordi laterali e il bordo basso del pannello (zone più larghe al dito).
• Ridimensionare — trascina gli angoli del pannello (in basso a destra compare un alone viola leggero); su touch i bordi sono zone ampie (circa 36–44 px).
• Iconizza — il pulsante «−» manda il pannello nella barra in basso (più comoda su tablet che trascinare finestre piccole).
• Pannello laterale — «⋕ Pannello» nasconde la colonna destra per avere tutto il canvas; su portrait la sidebar può occupare gran parte dello schermo.
• I pannelli non dovrebbero finire sotto la barra del sito: se succede, rilascia il dito e il sistema li riallinea; ruota in orizzontale o usa «Chiudi tutti» e riapri.
• HUD navigatore (pill in basso a destra) — stessa logica: trascina dalla barra del titolo; su touch le maniglie di resize sono più grandi.

Configurazione tecnica (solo gestori)

Il link Configurazione RAG apre l’area per Fusion, Provider AI, priorità modelli e impostazioni server. È protetta da password tecnica (CLINTEL_SETTINGS_PASSWORD nel server), non dalle credenziali dell’area riservata.

Se non sei incaricato della gestione, ignora questa sezione e usa solo Ricerche, Archivio e mappe. Per documentazione più tecnica sul workspace locale esiste anche guida utente workspace.