How it is planned to be implemented

This section describes the high-level implementation approach, without technical or API detail.

Request flow

For a detailed diagram showing the end-to-end path of a user message, see the Request Flow architecture page.

A form engine owns form configuration, validation, and navigation (e.g. which question comes next, branching). It does not handle natural language.
A chat layer sits on top: it receives user messages, decides the user’s intent, and either submits answers to the form engine, asks the knowledge base, or handles navigation and clarifications.
Configuration over code — Form definitions, prompts, and knowledge base settings are driven by config (YAML) so that behaviour can be tuned without changing application code. See the Configuration section for a complete reference.

Customer/tenant model — Each deployment or integration is tied to a customer (tenant). Access and configuration are scoped per customer.
Existing security integration — Authentication, authorization, and rate limiting are handled by an existing security layer (e.g. Keystone). The chat and form engine rely on that layer for identity and access; they do not implement their own auth.
Headers — The customer (and optionally language) are passed via headers and validated by the security layer before reaching the booking logic.

Short-lived sessions — Active conversation and form state are kept in a fast store (e.g. Redis) for quick access.
Long-term storage — When needed, sessions can be archived to a persistent store (e.g. MongoDB) for history or compliance.

Tool-call orchestration — A root LLM receives the user’s message along with phase-gated tools (form filling, knowledge, confirmation, greeting, language change, out-of-scope). The LLM selects which tool to call based on the conversation context and user message. No separate intent classification step is needed — tool selection IS classification.
Inline value extraction — When the user answers a form question, the inner form-filling LLM extracts structured values (dates, times, selections, etc.) inline as part of its submitAnswer tool call. The form engine validates the value and stores it. No separate extraction step or type-specific extractor classes.
Knowledge generation — For factual questions, retrieved knowledge-base content (PgVector RAG + file search) is used to generate concise, on-brand answers that naturally transition back to the booking flow.

This split keeps the form engine deterministic and testable, while the LLM tool-calling layer adds conversational and AI behaviour on top.