Chat DSL (Canvas)

A partire dalla v3.5.0 la pipeline di chat di Queria e una single source of truth canvas-native: il flusso che porta dalla domanda dell'utente alla risposta finale e descritto da un canvas DSL con purpose = CHAT, non piu da codice imperativo configurato tramite preset.

Cio significa che ogni azienda puo personalizzare l'orchestrazione AI (planner, retrieval, reranker, LLM writer, critic, citation pipeline) modificando il canvas, senza richiedere release di backend.

Cosa e cambiato dalle versioni precedenti

Nelle versioni 3.1.x la pipeline di chat era codificata in TypeScript e i preset RAG portavano ~18 sezioni di config. Oggi i preset contengono solo sector, tags[], domainTerms[] e chunking. Tutta la configurazione di chat e ricerca vive nel canvas DSL.

Canvas di sistema

Ogni azienda ha quattro canvas di sistema con purpose CHAT, immutabili come template ma copiabili e personalizzabili:

Canvas	Scopo	Entry point
chat-default	Pipeline standard chat web	POST /api/chat/stream
widget-default	Pipeline ottimizzata per widget embeddato	API key widget
search-default	Risposta breve "search-like" senza follow-up	POST /api/search
whatsapp-default	Output formattato per WhatsApp (markdown WhatsApp, split a 1500 char)	Webhook Twilio

Per attivare una variante personalizzata, l'admin:

1. Duplica il canvas di sistema.
2. Modifica il flusso nell'editor Canvas.
3. Lo associa al topic o all'intera azienda dalle impostazioni.

Anatomia di una pipeline chat

Una pipeline di chat tipica usa questi nodi (selezione - elenco completo in Canvas - Componenti):

Ingresso

• begin -- riceve userMessage, sessionId, userId, contextFilters.
• Variabili di sistema: sys.channel (web/widget/whatsapp), sys.userLanguage, sys.tenantSector.

Comprensione

• categorize -- classifica intent (fattuale, aggregativo, comparativo, esplorativo, generativo).
• llm_planner -- scompone query complesse in sub-query (sequenziali, parallele, gerarchiche, comparative).

Recupero

• retrieval -- ricerca ibrida (semantica + testo) su collezioni Qdrant. Configurabile per:
  • topK, scoreThreshold, diversityFactor
  • target collection (knowledge_base_{companyId}, user_docs_{conversationId})
  • filtri payload (sector, subSector, role, grade, confidentiality)
• external_tool -- chiama fonti esterne (Legal, Food, Chem, Pharma, AE, open-data) come nodi nativi del canvas.

Selezione

• rerank -- cross-encoder BGE-Reranker per riordinare risultati.
• data_operations -- filtri, deduplica, limiti per fonte.

Generazione

• llm_writer -- modello principale (Qwen3-Next-80B). Usa <think> interni gestiti dal parser.
• llm_critic (opzionale) -- valida la risposta, marca affermazioni non supportate dalle fonti.
• citation_pipeline -- post-processing per inserire [N] inline e costruire la mappa citazioni.

Uscita

• message -- emette la risposta in streaming SSE.
• channel_send (opzionale) -- per pipeline WhatsApp/Telegram, formatta e invia tramite adapter del canale.

Variabili e referenze

Il DSL usa la sintassi {{namespace.path}} per collegare i nodi:

{{begin.userMessage}}            # input utente
{{retrieval_1.formalized_content}} # testo recuperato
{{llm_planner_1.subQueries}}      # output JSON del planner
{{sys.channel}}                   # canale di origine
{{env.MAX_TOKENS_DEFAULT}}        # variabile d'ambiente sicura

Le variabili sensibili (secret, token) sono accessibili tramite connection_ref su nodi external_tool, mai inline nel DSL.

Kill-switch e fallback

Due flag di sistema permettono di attenuare in produzione senza modificare il canvas:

CHAT_PLANNER_ENABLED=true    # se false, salta llm_planner
CHAT_CRITIC_ENABLED=true     # se false, salta llm_critic

Utili per ridurre latenza o costo in scenari di carico. I canvas che usano questi nodi devono essere progettati con un edge di bypass alternativo.

Differenze rispetto ai preset

Aspetto	Preset (legacy)	Canvas DSL (v3.5.0+)
Topologia pipeline	Hard-coded in TS	Definita da nodi e edge
Parametri retrieval	retrieval.topK, etc. nel preset	Per-nodo nel canvas
Logica condizionale	No	Nodo switch
Iterazioni	No	Nodi iteration / loop
Personalizzazione per topic	Solo system prompt	Canvas dedicato per topic
Modifica senza release	No	Si, dall'editor web
Visibilita audit	Difficile	Snapshot DSL versionati

Per la migrazione storica dai preset vedi Preset RAG (slim).

Versioning e deploy

Ogni modifica al canvas crea uno snapshot versionato:

• Visibile in pagina Cronologia del canvas.
• Rollback a qualsiasi versione con un click.
• Per i topic, e possibile fissare la versione (es. "topic Legale usa snapshot v12") per evitare deploy involontari.

Pubblicazione graduale

Prima di sostituire un canvas di sistema su tutti gli utenti, abilita il nuovo canvas su un singolo topic interno e verifica le risposte. Solo dopo passa a tutta l'azienda.

Best practice

1. Parti dai canvas di sistema: copialo e personalizza, non costruire da zero.
2. Mantieni i nodi minimi necessari: ogni nodo aggiuntivo aumenta latenza.
3. Usa il critic solo dove conta: legale, sanitario, fiscale. Per chat informali puo essere disattivato.
4. Testa con il pannello Ragionamento: l'utente vede gli step in esecuzione, e una grande aiuto al debug.
5. Sfrutta i kill-switch in incidenti: planner e critic possono essere disattivati al volo se causano problemi.

---

Queria v3.5.0 -- Chat DSL canvas-native