Chat DSL (Canvas)

From v3.5.0 the Queria chat pipeline is a single source of truth canvas-native: the flow from user question to final answer is described by a canvas DSL with purpose = CHAT, no longer by imperative code configured via presets.

This means every company can customize the AI orchestration (planner, retrieval, reranker, LLM writer, critic, citation pipeline) by editing the canvas, with no need for backend releases.

What changed from earlier versions

In 3.1.x the chat pipeline was hardcoded in TypeScript and RAG presets carried ~18 config sections. Today presets only contain sector, tags[], domainTerms[] and chunking. All chat and retrieval configuration lives in the canvas DSL.

System canvases

Every company has four CHAT system canvases - immutable as templates but copiable and customizable:

Canvas	Purpose	Entry point
chat-default	Standard web chat pipeline	POST /api/chat/stream
widget-default	Pipeline optimized for embedded widget	Widget API key
search-default	Short "search-like" answer with no follow-up	POST /api/search
whatsapp-default	Output formatted for WhatsApp (WhatsApp markdown, hard split at 1500 chars)	Twilio webhook

To activate a custom variant, the admin:

1. Duplicates the system canvas.
2. Edits the flow in the Canvas editor.
3. Attaches it to a topic or to the whole company from settings.

Anatomy of a chat pipeline

A typical chat pipeline uses these nodes (selection - full list in Canvas - Components):

Input

• begin -- receives userMessage, sessionId, userId, contextFilters.
• System variables: sys.channel (web/widget/whatsapp), sys.userLanguage, sys.tenantSector.

Understanding

• categorize -- classifies intent (factual, aggregative, comparative, exploratory, generative).
• llm_planner -- decomposes complex queries into sub-queries (sequential, parallel, hierarchical, comparative).

Retrieval

• retrieval -- hybrid search (semantic + lexical) on Qdrant collections. Configurable for:
  • topK, scoreThreshold, diversityFactor
  • target collection (knowledge_base_{companyId}, user_docs_{conversationId})
  • payload filters (sector, subSector, role, grade, confidentiality)
• external_tool -- calls external sources (Legal, Food, Chem, Pharma, AE, open-data) as native canvas nodes.

Selection

• rerank -- BGE-Reranker cross-encoder to re-rank results.
• data_operations -- filters, deduplication, per-source limits.

Generation

• llm_writer -- primary model (Qwen3-Next-80B). Uses internal <think> handled by the parser.
• llm_critic (optional) -- validates the answer, flags claims not supported by the sources.
• citation_pipeline -- post-processing to inject [N] inline and build the citation map.

Output

• message -- streams the response over SSE.
• channel_send (optional) -- for WhatsApp/Telegram pipelines, formats and sends via the channel adapter.

Variables and references

The DSL uses the syntax {{namespace.path}} to link nodes:

{{begin.userMessage}}              # user input
{{retrieval_1.formalized_content}} # retrieved text
{{llm_planner_1.subQueries}}       # planner JSON output
{{sys.channel}}                    # source channel
{{env.MAX_TOKENS_DEFAULT}}         # safe env variable

Sensitive variables (secret, token) are accessible via connection_ref on external_tool nodes, never inline in the DSL.

Kill-switches and fallback

Two system flags allow throttling in production without changing the canvas:

CHAT_PLANNER_ENABLED=true    # if false, skip llm_planner
CHAT_CRITIC_ENABLED=true     # if false, skip llm_critic

Useful to reduce latency or cost under load. Canvases that use these nodes must be designed with an alternative bypass edge.

Differences from presets

Aspect	Preset (legacy)	Canvas DSL (v3.5.0+)
Pipeline topology	Hard-coded in TS	Defined by nodes and edges
Retrieval parameters	retrieval.topK, etc. in preset	Per-node in canvas
Conditional logic	No	switch node
Iterations	No	iteration / loop nodes
Per-topic customization	Only system prompt	Dedicated canvas per topic
Modification without release	No	Yes, from the web editor
Audit visibility	Hard	Versioned DSL snapshots

For the historical migration from presets see Slim RAG Presets.

Versioning and deploy

Every canvas change creates a versioned snapshot:

• Visible in the canvas History page.
• Rollback to any version with one click.
• For topics, you can pin a version (e.g. "Legal topic uses snapshot v12") to avoid involuntary deploys.

Gradual rollout

Before replacing a system canvas across all users, enable the new canvas on a single internal topic and verify the answers. Only then switch the whole company.

Best practices

1. Start from system canvases: copy and customize, do not build from scratch.
2. Keep the minimum nodes needed: every extra node adds latency.
3. Use the critic only where it matters: legal, healthcare, tax. For informal chat it can be disabled.
4. Test with the Reasoning panel: the user sees the running steps, great for debugging.
5. Lean on kill-switches in incidents: planner and critic can be turned off on the fly if causing issues.

---

Queria v3.5.0 -- Canvas-native Chat DSL