Chat DSL (Canvas)

A partir de la v3.5.0 la pipeline de chat de Queria es un single source of truth canvas-native: el flujo de la pregunta del usuario hasta la respuesta final esta descrito por un canvas DSL con purpose = CHAT, ya no por codigo imperativo configurado mediante presets.

Esto significa que cada empresa puede personalizar la orquestacion IA (planner, retrieval, reranker, LLM writer, critic, citation pipeline) modificando el canvas, sin necesidad de releases de backend.

Que cambia respecto a versiones anteriores

En 3.1.x la pipeline estaba en TypeScript y los presets RAG llevaban ~18 secciones de config. Hoy los presets contienen solo sector, tags[], domainTerms[] y chunking. Toda la configuracion de chat y busqueda vive en el canvas DSL.

Canvas de sistema

Cada empresa tiene cuatro canvas de sistema con CHAT, inmutables como plantillas pero copiables y personalizables:

Canvas	Proposito	Entry point
chat-default	Pipeline estandar chat web	POST /api/chat/stream
widget-default	Pipeline optimizada para widget embedido	API key widget
search-default	Respuesta breve "search-like" sin follow-up	POST /api/search
whatsapp-default	Salida formateada para WhatsApp (markdown WhatsApp, split a 1500 char)	Webhook Twilio

Para activar una variante personalizada el admin:

1. Duplica el canvas de sistema.
2. Modifica el flujo en el editor Canvas.
3. Lo asocia al topic o a la empresa entera desde la configuracion.

Anatomia de una pipeline de chat

Una pipeline tipica usa estos nodos (seleccion - lista completa en Canvas - Componentes):

Entrada

• begin -- recibe userMessage, sessionId, userId, contextFilters.
• Variables de sistema: sys.channel (web/widget/whatsapp), sys.userLanguage, sys.tenantSector.

Comprension

• categorize -- clasifica intent (factual, agregativo, comparativo, exploratorio, generativo).
• llm_planner -- descompone consultas complejas en sub-consultas (secuenciales, paralelas, jerarquicas, comparativas).

Recuperacion

• retrieval -- busqueda hibrida (semantica + texto) sobre colecciones Qdrant. Configurable para:
  • topK, scoreThreshold, diversityFactor
  • target collection (knowledge_base_{companyId}, user_docs_{conversationId})
  • filtros payload (sector, subSector, role, grade, confidentiality)
• external_tool -- llama a fuentes externas (Legal, Food, Chem, Pharma, AE, open-data) como nodos nativos del canvas.

Seleccion

• rerank -- cross-encoder BGE-Reranker para reordenar resultados.
• data_operations -- filtros, deduplicacion, limites por fuente.

Generacion

• llm_writer -- modelo principal (Qwen3-Next-80B). Usa <think> internos gestionados por el parser.
• llm_critic (opcional) -- valida la respuesta, marca afirmaciones no respaldadas por fuentes.
• citation_pipeline -- post-procesamiento para insertar [N] inline y construir el mapa de citas.

Salida

• message -- emite la respuesta en streaming SSE.
• channel_send (opcional) -- para pipelines WhatsApp/Telegram, formatea y envia mediante adapter del canal.

Variables y referencias

El DSL usa la sintaxis {{namespace.path}} para conectar los nodos:

{{begin.userMessage}}              # input usuario
{{retrieval_1.formalized_content}} # texto recuperado
{{llm_planner_1.subQueries}}       # output JSON del planner
{{sys.channel}}                    # canal de origen
{{env.MAX_TOKENS_DEFAULT}}         # variable de entorno segura

Las variables sensibles (secret, token) son accesibles via connection_ref en nodos external_tool, nunca inline en el DSL.

Kill-switch y fallback

Dos flags de sistema permiten atenuar en produccion sin modificar el canvas:

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

Utiles para reducir latencia o coste en escenarios de carga. Los canvas que usan estos nodos deben disenarse con un edge alternativo de bypass.

Diferencias con los presets

Aspecto	Preset (legacy)	Canvas DSL (v3.5.0+)
Topologia pipeline	Hard-coded en TS	Definida por nodos y edges
Parametros retrieval	retrieval.topK, etc. en preset	Por-nodo en el canvas
Logica condicional	No	Nodo switch
Iteraciones	No	Nodos iteration / loop
Personalizacion por topic	Solo system prompt	Canvas dedicado por topic
Modificacion sin release	No	Si, desde el editor web
Visibilidad audit	Dificil	Snapshots DSL versionados

Para la migracion historica desde los presets ver Presets RAG (slim).

Versionado y deploy

Cada modificacion del canvas crea un snapshot versionado:

• Visible en la pagina Historial del canvas.
• Rollback a cualquier version con un clic.
• Para los topics, es posible fijar la version (ej. "topic Legal usa snapshot v12") para evitar deploys involuntarios.

Publicacion gradual

Antes de sustituir un canvas de sistema en todos los usuarios, habilita el nuevo canvas en un solo topic interno y verifica las respuestas. Solo despues pasa a toda la empresa.

Best practice

1. Parte de los canvas de sistema: copia y personaliza, no construyas desde cero.
2. Manten los nodos minimos necesarios: cada nodo extra aumenta latencia.
3. Usa el critic solo donde importa: legal, sanitario, fiscal. Para chat informales puede desactivarse.
4. Prueba con el panel de Razonamiento: el usuario ve los steps en ejecucion, una gran ayuda al debug.
5. Aprovecha los kill-switches en incidentes: planner y critic pueden desactivarse al vuelo si causan problemas.

---

Queria v3.5.0 -- Chat DSL canvas-native