Cog-RAG: Cognitive Retrieval-Augmented Generation

Cog-RAG e' l'architettura proprietaria di Queria che trasforma la ricerca documentale da un processo meccanico a un processo cognitivo. Invece di limitarsi a trovare documenti simili a una domanda, il sistema comprende, pianifica, ragiona e verifica prima di rispondere.

A partire dalla v3.5.0 l'intero ciclo Cog-RAG e' implementato come canvas DSL (purpose = CHAT), una pipeline grafica composta da nodi tipizzati che il tenant puo' personalizzare senza scrivere codice. Lo stesso pattern si applica all'ingestione (purpose = INGESTION) e alle integrazioni esterne (purpose = SERVICE per OAuth).

Vedi anche

• Chat DSL (Canvas) -- come configurare la pipeline di chat per la propria azienda
• Ingestion DSL -- pipeline di ingestione role-aware
• OAuth e Service Canvas -- integrazioni autenticate

Il problema del RAG tradizionale

Un sistema RAG classico segue tre passaggi:

1. Riceve la domanda dell'utente
2. Cerca i documenti piu' simili nel database vettoriale
3. Passa i documenti trovati al modello linguistico per generare la risposta

Questo approccio ha limiti evidenti. Non gestisce domande complesse che richiedono informazioni da fonti diverse. Non adatta la strategia di ricerca alla complessita' della domanda. Non verifica se i risultati trovati sono realmente pertinenti. Non e' in grado di ragionare su piu' documenti per produrre una sintesi. Non ha memoria di chi sta parlando o di cosa e' gia' stato chiesto in precedenza.

Da RAG a Cog-RAG agentico con memoria

L'architettura di Queria evolve il RAG tradizionale lungo tre assi:

1. Cognitivo (Cog) -- il sistema comprende l'intento, pianifica la strategia, scompone le query e verifica il grounding prima di rispondere.
2. Agentico -- pattern ReAct multi-step: il motore esegue una catena di osservazione, ragionamento e azione (chiamata a strumenti, recupero, sintesi), ripetuta fino a convergenza o limite di iterazioni.
3. Con memoria -- ogni utente ha un Memory Subject persistente che conserva fatti, preferenze e contesto tra conversazioni diverse. Il bot ricorda chi sei, su cosa stai lavorando, cosa hai gia' visto.

L'insieme dei tre assi e' implementato come un canvas DSL personalizzabile. Cio' che segue descrive il flusso "di sistema" -- punto di partenza per ogni tenant, modificabile senza release di backend.

Come funziona Cog-RAG agentico

Cog-RAG introduce un ciclo cognitivo completo tra la domanda e la risposta, memory-aware e agentic:

                                  [Memory recall]
                                        |
                                        v
Domanda  ----->  [Memory subject + conversation history] -----> contesto
   |                                                                 |
   v                                                                 |
[1] Analisi e comprensione della query (con contesto utente)        |
   |                                                                 |
   v                                                                 |
[2] Pianificazione della strategia di ricerca                       |
   |                                                                 |
   v                                                                 |
[3] Decomposizione in sotto-query (se necessario)                   |
   |                                                                 |
   v                                                                 |
[4] *Loop agentico ReAct*                                           |
   |   |                                                             |
   |   v                                                             |
   |  Action: chiamata a strumenti (retrieval, external_tool, ...) <-+
   |   |
   |   v
   |  Observation: risultati strumenti
   |   |
   |   v
   |  Reasoning: critic valuta sufficienza
   |   |
   |   v
   |  (converge?) --no--> nuova action
   |   |
   |   si
   |
   v
[5] Riordinamento semantico (reranking)
   |
   v
[6] Verifica qualita' e grounding (critic)
   |          |
   |     (insufficiente)
   |          |
   |          v
   |     Ritorno al loop agentico
   |     con scope ampliato
   |
   v
[7] Sintesi con ragionamento profondo
   |
   v
[8] Update memoria (fatti persistenti emersi)
   |
   v
Risposta con citazioni

Ogni passaggio e' un nodo del canvas, gestito da componenti specializzati che collaborano in modo autonomo. Il critic -- un nodo LLM dedicato -- valuta a ogni iterazione se le evidenze raccolte sono sufficienti e accurate; se non lo sono, il sistema rilancia il loop con scope ampliato. La conversazione si chiude solo quando il critic d'accordo o si raggiunge il limite di iterazioni configurato.

Memoria persistente per-utente

Una caratteristica distintiva di Cog-RAG v3.5.0 e' la memoria persistente che il sistema mantiene per ciascun utente, attraverso conversazioni diverse e canali diversi (web, widget, WhatsApp).

Memory Subject

Ogni utente ha un Memory Subject -- una struttura in DB che raccoglie:

Categoria	Contenuto	Esempi
Profilo professionale	Ruolo, area di responsabilita', dominio di interesse	"Responsabile compliance", "lavora sui contratti GDPR"
Preferenze	Stile di risposta, lingua, livello di dettaglio	"vuole risposte brevi", "preferisce italiano"
Contesto operativo	Su cosa sta lavorando, scadenze, progetti aperti	"sta analizzando il bilancio 2025", "deadline 31 dicembre"
Riferimenti	Documenti, clienti, fornitori menzionati di frequente	"lavora spesso sul fornitore Rossi srl"

Il Memory Subject e' isolato per (userId, companyId): nessun dato di un utente fluisce verso un altro, nemmeno all'interno della stessa azienda.

Tre livelli di memoria

+-----------------------------+
|  Memoria intra-conversazione |  ultime N message (turni)
+-----------------------------+
              |
              v
+-----------------------------+
|  Cronologia conversazioni   |  riassunti di sessioni precedenti
+-----------------------------+
              |
              v
+-----------------------------+
|  Memory Subject (persistente)|  fatti, preferenze, contesto utente
+-----------------------------+

1. Intra-conversazione: l'assistente ricorda esattamente cio' che e' stato detto nei turni precedenti della stessa chat. Puoi fare riferimento a "il punto 3 della risposta precedente" senza ripeterlo.
2. Cronologia conversazioni: riassunti compatti delle conversazioni passate consultabili al volo. Utile per riprendere un argomento aperto giorni fa.
3. Memory Subject: fatti chiave estratti automaticamente o segnalati esplicitamente. Persistono finche' l'utente non li rimuove dal proprio profilo memoria.

Aggiornamento della memoria

Un nodo memory_writer al termine del canvas estrae dai turni completati informazioni candidate da promuovere nel Memory Subject. La promozione e' sempre trasparente: l'utente vede una notifica "ho memorizzato che..." e puo' rifiutare la promozione, oppure consultare il proprio profilo memoria dalle impostazioni.

Privacy della memoria

• Lato utente: la pagina Profilo > Memoria mostra tutti i fatti memorizzati, con possibilita' di modifica e cancellazione puntuale.
• Lato amministratore: SYSTEM_ADMIN puo' visualizzare la memoria aggregata di un'azienda solo per audit, mai contenuti per singolo utente senza esplicito mandato.
• Cancellazione utente: tutti i Memory Subject associati vengono rimossi con cascade.

Per la guida lato utente vedi Memoria e Contesto.

Il sistema a due cervelli

Al centro di Cog-RAG operano due modelli AI con ruoli complementari:

Planner: il cervello veloce

Il Planner e' un modello rapido e leggero, ottimizzato per decisioni immediate. Si occupa di:

• Classificazione dell'intento: capisce cosa l'utente sta realmente chiedendo
• Routing: decide quale pipeline attivare (ricerca semplice, decomposizione, confronto)
• Decomposizione delle query: scompone domande complesse in sotto-domande gestibili
• Valutazione della complessita': stima la difficolta' della domanda per calibrare i parametri di ricerca
• Utility e supporto: gestisce operazioni ausiliarie come riformulazione e riassunti rapidi

Il Planner opera in millisecondi e non impegna risorse computazionali pesanti.

Writer: il cervello profondo

Il Writer e' un modello potente con capacita' di ragionamento avanzato. Si occupa di:

• Sintesi multi-documento: combina informazioni da decine di fonti in una risposta coerente
• Ragionamento complesso: affronta domande che richiedono inferenze, confronti, analisi
• Generazione di alta qualita': produce testi professionali, strutturati e accurati
• Pensiero esplicito: utilizza un processo di ragionamento interno (thinking) prima di formulare la risposta

Il Writer entra in gioco solo quando serve la sua potenza, preservando l'efficienza complessiva del sistema.

La collaborazione

Il Planner decide cosa fare e come farlo. Il Writer esegue con profondita'. Questa separazione permette di ottenere tempi di risposta rapidi per domande semplici (gestite quasi interamente dal Planner) e risposte di alta qualita' per domande complesse (dove il Writer investe tempo nel ragionamento).

Il Critic

Al pattern agentic si affianca un terzo ruolo: il Critic. E' una istanza LLM dedicata che, dopo ogni azione del Writer, valuta il risultato lungo dimensioni esplicite (sufficienza delle evidenze, contraddizioni interne, allineamento con la domanda originale, copertura delle sotto-query). Se l'analisi fallisce uno o piu' criteri, il critic emette un rinvio al loop agentico con istruzioni mirate (es. "ricerca anche su sorgenti normative", "approfondisci l'aspetto X").

Il Critic e' attivabile tramite kill-switch CHAT_CRITIC_ENABLED. In scenari latency-critical puo' essere disabilitato; in scenari mission-critical (legale, sanitario, fiscale) e' sempre attivo.

Pattern agentic e tool use

In modalita' agentic, il Writer non si limita a sintetizzare: e' un agente che decide quali strumenti invocare per arrivare alla risposta. Gli strumenti disponibili nel canvas sono:

Tipo strumento	Esempi
Retrieval interno	Ricerca su collezioni Qdrant del tenant (KB, user docs, sector)
External sources	Legal Sources, Food Sources, Chem Sources, Pharma Sources, AE Sources
External tools via OAuth	Slack post_message, Stripe customer.lookup, GCal create_event
Open data	Geocoding (Nominatim), POI (Overpass), meteo (Open-Meteo), enciclopedia (Wikipedia)
AI Constructor	Pipeline settoriali pre-impacchettate (Tourism, in roadmap Fiscale, Sanitario)
Memory lookup	Interrogazione del Memory Subject dell'utente corrente

Ogni strumento e' un nodo del canvas. L'agente sceglie iterativamente quale invocare osservando i risultati precedenti e ragionando sul gap rispetto alla domanda. Tutta la sequenza e' tracciata e visibile nel pannello di ragionamento.

Orchestrazione delle query

Non tutte le domande sono uguali. Cog-RAG classifica ogni query e sceglie la strategia di orchestrazione piu' adatta.

Query semplici

Per domande dirette con una risposta attesa chiara, il sistema esegue una ricerca diretta e genera la risposta. Nessuna decomposizione, nessun passaggio superfluo.

Esempio: "Qual e' la data di scadenza del contratto con il fornitore X?"

Decomposizione sequenziale

Quando le sotto-domande dipendono l'una dall'altra, vengono eseguite in sequenza. La risposta di una sotto-domanda alimenta la successiva.

Esempio: "Chi sono gli eredi designati nel testamento e quali quote spettano a ciascuno?" Prima si identificano gli eredi, poi si cercano le quote per ciascuno.

Decomposizione parallela

Quando le sotto-domande sono indipendenti, vengono eseguite in parallelo per massimizzare la velocita'.

Esempio: "Confronta le condizioni contrattuali del fornitore A con quelle del fornitore B." Le ricerche sui due fornitori avvengono simultaneamente.

Decomposizione gerarchica

Per domande esplorative, il sistema parte dal generale e approfondisce progressivamente.

Esempio: "Quali sono le principali problematiche emerse nei rapporti di audit dell'ultimo anno?" Prima una ricerca ampia, poi approfondimenti mirati sulle tematiche emerse.

Decomposizione comparativa

Per confronti strutturati, il sistema raccoglie informazioni da entrambe le parti e produce un'analisi side-by-side.

Esempio: "Quali differenze ci sono tra la polizza assicurativa attuale e quella proposta?"

Ricerca adattiva

I parametri di ricerca si calibrano automaticamente in base alla complessita' stimata della query:

Complessita'	Documenti cercati	Soglia minima	Reranking	Diversificazione
Semplice	Pochi, mirati	Alta	Si'	Bassa
Moderata	Media quantita'	Media	Si'	Media
Complessa	Ampia quantita'	Bassa	Si'	Alta
Aggregativa	Copertura massima	Molto bassa	No	Massima

Le query aggregative (statistiche, riassunti di grandi insiemi) richiedono un approccio diverso: massima copertura con diversificazione alta per evitare risultati ridondanti.

Ricerca ibrida

Ogni ricerca combina due approcci complementari:

• Ricerca semantica: confronta il significato della domanda con il significato dei documenti attraverso vettori a 1024 dimensioni. Eccelle nel trovare documenti pertinenti anche quando le parole sono diverse.

• Ricerca lessicale (BM25): confronta le parole chiave. Eccelle nel trovare documenti con termini specifici (codici, nomi propri, numeri di articolo).

I risultati delle due ricerche vengono combinati tramite Reciprocal Rank Fusion (RRF), un algoritmo che bilancia i punteggi di entrambi gli approcci per produrre un ranking finale ottimale.

Integrazione multi-sorgente

Cog-RAG non si limita ai documenti aziendali. Il sistema integra in modo trasparente:

• Documenti aziendali: i file caricati dall'organizzazione
• Knowledge Base: la base di conoscenza curata e permanente
• Sorgenti esterne certificate: banche dati specializzate in ambito legale, alimentare, chimico e farmaceutico

Tutte le fonti partecipano allo stesso processo di ricerca e reranking. L'utente riceve una risposta unificata con citazioni che identificano chiaramente l'origine di ogni informazione attraverso badge colorati distinti per tipo di fonte.

Ragionamento trasparente

Una delle caratteristiche distintive di Cog-RAG e' la trasparenza del processo di ragionamento. Il Writer utilizza una modalita' di thinking esplicito: prima di formulare la risposta, genera un ragionamento interno in cui analizza le fonti, valuta la pertinenza, identifica eventuali contraddizioni e pianifica la struttura della risposta.

Questo ragionamento e' visibile all'utente attraverso il pannello dedicato nell'interfaccia. L'utente puo' verificare come il sistema e' arrivato a una determinata conclusione, quali fonti ha considerato rilevanti e perche', e dove ha trovato eventuali lacune informative.

La trasparenza del ragionamento e' fondamentale in contesti enterprise dove le decisioni basate sulle risposte del sistema devono essere verificabili e giustificabili.

Personalizzabilita' via canvas DSL

A differenza delle architetture RAG monolitiche, Cog-RAG v3.5.0 e' interamente costruito sui canvas DSL. Cio' significa che:

• Ogni tenant puo' duplicare la pipeline di sistema e modificarla -- aggiungere strumenti, cambiare l'ordine dei nodi, escludere il critic, aggiungere step di sanitizzazione PII prima dell'invio del prompt.
• Ogni topic puo' avere una pipeline dedicata (es. il topic "Compliance" usa critic + sorgenti normative obbligatorie, il topic "Marketing" usa una pipeline piu' libera).
• I canvas sono versionati: snapshot, rollback, audit immutabile delle versioni passate.
• I cambi di pipeline non richiedono release del backend.

Per l'editor canvas, i nodi disponibili e gli esempi vedi la sezione Canvas Agent Builder.

Riepilogo v3.5.0

Dimensione	Implementazione
Cognitivo	Planner + Writer + Critic, decomposizione adattiva, ricerca ibrida
Agentico	Pattern ReAct multi-step, tool use dinamico, convergenza guidata dal critic
Memoria	Memory Subject persistente per (user, company), tre livelli (intra-conversazione, cronologia, profilo)
DSL-native	Canvas tipizzati per CHAT / INGESTION / SERVICE / WIDGET con purpose distinti
Multi-sorgente	Documenti tenant + KB + 5 external sources + open data + OAuth tools
Multi-canale	Web app, widget incorporato, WhatsApp via Twilio (V1)
Trasparenza	Pannello ragionamento visibile, audit immutabile snapshot canvas
Privacy	Isolamento multi-tenant, memoria utente-locale, AI on-prem (DGX Spark)