CLINTELITALIA — workspace scientifico

Questo progetto raccoglie strumenti per leggere e interrogare documentazione scientifica e tecnica legata al clima e alle politiche energetiche, nel solco della missione di CLINTELITALIA: portare chiarezza, non slogan. Non sostituisce il giudizio umano, la lettura integrale delle fonti né il dibattito tra esperti.

Il sistema combina un motore RAG (ricerca semantica su un corpus che controlli in locale o in ambiente dedicato) con APPRENDO, un servizio di mappe concettuali (grafo) alimentate da modelli di linguaggio. È un tentativo onesto di ridurre il rumore e accelerare l’orientamento tra fonti; può sbagliare, omettere o enfatizzare in modo non voluto: per questo va usato con spirito critico, citando sempre le fonti recuperate.

• Non è l’oracolo di Delfi: le risposte sono ricostruzioni statistiche su testi e modelli; non hanno autorevolezza intrinseca.
• Non è verità normativa: nulla qui fissa posizioni giuridiche o policy ufficiali.
• Non è garanzia di completezza: ciò che non è indicizzato non esiste per il RAG; ciò che il modello non estrae non compare nel grafo.
• Non è anonimato verso te stesso: in installazioni locali, chi amministra la macchina vede log, file e configurazioni.

Il workspace usa due servizi distinti:

• CLINTEL (Ricerche) — dashboard, ricerca sul corpus, indicizzazione, bridge verso le mappe. Origine “Ricerche” nel navigatore.
• APPRENDO (mappe) — analisi testo/PDF, creazione e modifica grafi, archivio, provider LLM per i grafi. Origine “APPRENDO” nel navigatore.

Se Ricerche e APPRENDO sono su indirizzi diversi, il browser li tratta come origini separate: alcune memorie locali (es. elenco grafi recenti) non si mescolano da sole; una parte del codice sincronizza un riassunto quando sei sulle Ricerche.

Pagine statiche come /static/gorag.html o /static/clintai_intro.html possono essere servite dallo stesso host della ricerca: il contesto guida le etichette “RAG” / “Intro”.

Schermata di ingresso: riepilogo stato (chunk indicizzati, file, modello), accesso rapido alla ricerca, avvio indicizzazione. È il posto giusto per capire se il backend risponde e se il corpus è aggiornato prima di interrogazioni lunghe.

Da qui passa anche la narrativa “ufficiale” del progetto; la guida online ripete in forma operativa ciò che serve nel lavoro quotidiano.

Interfaccia principale del RAG: scrivi una domanda in linguaggio naturale, scegli quante fonti richiedere, lingua e (se previsto) il provider LLM condiviso. Il sistema recupera chunk dall’indice e costruisce una risposta con citazioni ai passaggi.

Ingresso canonico: dall’host delle Ricerche CLINTEL usa il percorso /ricerca oppure apri Ricerche CLINTEL →.

Buone pratiche

• Formulare domande scomponibili: è spesso meglio due ricerche puntuali che un unico interrogativo enorme.
• Controllare sempre estratti e percorsi file mostrati: sono l’evidenza effettivamente usata.
• Usare approfondimenti e pannelli secondari quando l’UI li offre, ma tenerne traccia mentalmente degli obiettivi (evitare finestre perdute).

Grafo APPRENDO da qui

Con apprendo_map in esecuzione e variabili (APPRENDO_MAP_URL, ecc.) coerenti, puoi generare una mappa concettuale che attinge agli stessi risultati di indice della ricerca. La scheda grafo usa una pagina di avanzamento chiara prima di caricare la mappa: non è un blocco inspiegabile, è l’attesa del server.

Variante di interfaccia servita come file statico nel repo: usa le stesse idee della ricerca (domanda → indice → risposta) con layout dedicato. Se la apri dall’installazione locale, assicurati che le API puntino allo stesso backend attivo (/api/cerca e correlate). La guida contestuale marcatà questo percorso come “RAG”.

Pagina di presentazione del motore e della filosofia CLINTEL: utile da condividere con chi deve capire cosa sia il sistema senza usarlo ancora. Non esegue ricerche pesanti ma contestualizza tono e limiti.

Servizio per costruire e navigare grafi di concetti estratti da testi o PDF lunghi tramite pipeline di chunk e prompt tecnici/ricchi. Qui il modello genera nodi/archi XML che diventano un’interfaccia esplorabile.

Pagina grafo (/grafo/<id>)

Visualizzazione e arricchimento della mappa: espansione nodi, aggiunta manuale, export, collegamenti a Ricerche quando configurati. Salva nel navigatore il grafo attivo così puoi tornarci dall’HUD.

Archivio (/archivio)

Elenco mappe salvate sul disco configurato dall’istanza APPRENDO; utile quando lavori su più temi contemporaneamente.

Provider / modelli (/provider)

Configura chiavi, endpoint locali (Ollama ecc.) e profili disponibili sul servizio APPRENDO. Separato dall’admin condiviso del motore Ricerche quando presente.

Ricerca globale in APPRENDO (/cerca)

Interrogazione trasversale sugli archetipi contenuti nelle mappe registrate dall’istanza—in dipendenza dalla versione e dalla configurazione del tuo fork.

Pannello sempre visibile su molte pagine: mostra dove sei, i grafi recenti (memoria browser: non è backup server) e link rapidi verso APPRENDO o Ricerche. Su Ricerche, un iframe legge la memoria locale di APPRENDO per mostrare anche i grafi aperti lì; i duplicati per URL vengono unificati.

Il pannello è ridimensionabile dai bordi/angoli (tranne il bordo destro centrale, per non coprire la scrollbar) e la geometria resta in sessionStorage durante la sessione.

Questa pagina guida non carica più il navigatore (per ridurre rumore visivo). Su Ricerche, grafo, archivio e altre viste operative trovi la pill in basso a destra; da lì, tra i collegamenti, c’è anche l’ingresso alla Guida all’utilizzo del RAG in linguaggio semplice.

Flusso che parte da Ricerche (o da gorag): seconda passata sull’indice, invio estratti a APPRENDO, creazione mappa. Richiede entrambi i servizi vivi e variabili coerenti (APPRENDO_MAP_URL sul lato CLINTEL, `CLINTEL_RICERCA_URL` opzionale sul lato APPRENDO per breadcrumb inversi). Se qualcosa manca, i messaggi di errore compaiono sia nella pagina ricerca sia nella scheda di lavoro.

Non sostituisce la documentazione interna del deploy, ma questi elementi spiegano il 90% degli “non funziona”:

• APPRENDO_MAP_URL — dove CLINTEL trova APPRENDO per il bridge.
• Porte processi — evitare di avere un vecchio Python in ascolto sulla porta sbagliata mentre credi di usare l’ultima build.
• Percorsi corpus e DB chunk — se la dashboard mostra zero chunk, la ricerca non avrà materiale.
• Provider LLM — chiavi e modelli validi per l’host che li consuma (Ricerche vs APPRENDO possono differire).

• «Non trova il documento che ho appena messo nella cartella» — finché non esegui l’indicizzazione e il processo conferma nuovi chunk, il RAG non può usarlo.
• «La risposta cita sempre gli stessi file» — aumenta diversità della domanda, controlla filtro lingua, verifica dimensione corpus; alcuni PDF potrebbero non essere stato estratto bene.
• «Grafo APPRENDO a pagina quasi vuota poi si apre» — normale mentre il POST è lungo: la scheda mostra stato e percentuali; non chiuderla prima del messaggio di fine o errore.
• «Navigatore senza graf che avevo su APPRENDO» — apri Ricerche con CLINTEL in esecuzione e APPRENDO raggiungibile: il pannello prova a sincronizzare l’elenco remoto nell’iframe di sync.

• Qualità del corpus: spazzatura in ingresso → rumore in uscita.
• Allucinazioni: possibili soprattutto se le fonti sono scarse o la domanda forza generalizzazioni.
• Costi e tempi: modelli cloud o GPU lenta influenzano latenza e costi; modelli locali dipendono dalla macchina.
• Aggiornamento: una risposta non riflette documenti aggiunti dopo l’indicizzazione finché non re-indicizzi.

Se qualcosa ti sembra sospetto, la procedura sana è: ripetere la domanda, cambiare modello, aprire il PDF, segnalare internamente a CLINTEL per migliorare corpus o prompt.

Route come /admin/provider-ai e /admin/fusione servono a gestire provider condivisi, profili di fusione e strumenti di supporto per chi amministra l’istanza. Richiedono di solito permessi elevati; non esporle su reti pubbliche senza protezione. Leggi sempre i messaggi di salvataggio e tieni traccia delle chiavi API fuori dal versionamento.