Skip to main content

WebClient AI chat

The AI chat in the report right-side pane of the legacy WebClient (InsFocusBI.WebClient, jQuery + Razor, DEV-731). An LLM router classifies every message, then the matching pipeline creates a report, alters it, or answers a question. Pane layout and Insights: BI report generator and insights.

Architecture​

  • wwwroot/Scripts/Report/AiReportChat.js — chat controller. Builds the payload, renders replies, keeps per-tab state on ReportTabManager (_aiLastReportJson, _aiHistory, _aiChatSending).
  • Controllers/AiController.cs — SendMessage. Resolves the current report (CurrentReport, or DescribeExistingReport(CurrentReportParameters)), calls HandleTurnAsync, logs stages to AiChatLog.
  • Ai/AiReportBL.cs — HandleTurnAsync, ClassifyIntentAsync, RouteIntent, GenerateAsync, AlterAsync, AnswerQuestionAsync.
  • Ai/AiIntent.cs — router output { IntentCode, Message, ResolvedRequest }. Tolerant TryParse. Unparseable → UNKNOWN. A blank IntentCode keeps the model's Message.
  • Server/InsFocusBI.Server.Data/BL/AI/ChatbotBL.cs — only caller of IChatClient. Overloads take a per-call modelId and prior turns ([System, …history, User]).
  • IChatClient — singleton, provider from Ai.Provider (Anthropic default, OpenAI), with UseFunctionInvocation() for the get_dimension_values tool.
  • Ai/AiChatModels.cs — AiChatRequest (Message, ReportKey, CurrentReport, CurrentReportParameters, History). AiReportPayload.Action tells the frontend "created" vs "altered".
  • Tests: WebClient/InsFocusBI.WebClient.Tests/AiIntentRoutingTests.cs.

Lifecycle of a turn​

  1. Frontend sends Message, ReportKey, the current report, and the last turns as History.
  2. Router runs the intent prompt on Ai.IntentModel, with the current report and the conversation.
  3. Router returns IntentCode and ResolvedRequest (the turn rewritten as a standalone request).
  4. Dispatch:
    • NEW_REPORT → GenerateAsync(ResolvedRequest).
    • ALTER_REPORT_PARAMS → AlterAsync. No open report → a clarification reply.
    • QUESTION → AnswerQuestionAsync. Text answer grounded in the tenant semantic model. Gets prior turns as chat messages.
    • UNKNOWN → the router's Message.
  5. A built report returns InputPaneParameters + GeneratedReportJson. The frontend applies it and sends it back as CurrentReport next turn.

Existing reports​

  • A report opened from the library runs automatically. Chat on it must alter it, not create a new one.
  • First turn on an already-run, non-dashboard report (ReportType == Report, !IsNotRunYet): the client sends the live InputPaneParameters as CurrentReportParameters (isExistingRunReport(rtm) in AiReportChat.js).
  • AiReportBL.DescribeExistingReport(json) parses them and calls GeneratedReportMapper.Describe(InputPaneParameters), the inverse of Build. Output is GeneratedReport JSON with IDs/PKs, used as CurrentReport.
  • Blank or unparseable parameters → null → no current report.
  • After the AI builds a report, _aiLastReportJson is sent as CurrentReport instead.
  • Test: describe → build round-trip in WebClient/InsFocusBI.WebClient.Tests/GeneratedReportMapperTests.cs.

Prompts​

  • Stored in the InsFocus_AI database, table Prompts, key (PromptKey, Language, Part).
  • Parts: main (fixed), insfocus and client (editable context).
  • Defaults live in Server/InsFocusBI.Server.Data/DAL/AI/PromptDefaults.cs. AIContextInitializer tops up missing rows at startup and never overwrites edits. A new prompt key needs no migration.
  • Keys used by chat: intent, question, creation, creation_alter (+ staged creation_*).
  • intent placeholders include {{HISTORY}} (conversation block).
  • SystemCenter prompt editor (ClientApp/src/app/settings/components/ai-prompts/ai-prompts.component.ts) has a fixed promptKeys list. Add new keys there to make them editable. It includes intent and question.

Conversation history​

  • Client-side only. Per report tab in rtm._aiHistory.
  • Sends the last 10 turns, each capped at 4000 chars. Both user and assistant turns. Never includes the current message.
  • Lost on page refresh.
  • The router interprets history and writes ResolvedRequest. Create/alter prompts get only the rewrite, not the transcript.

Rendering​

  • Assistant replies and result-card bodies render through renderMarkdown() in AiReportChat.js.
  • It HTML-escapes the whole string first, then adds a safe subset: headings, bold/italic, inline and fenced code, lists, links.
  • Links only for http(s) and mailto.
  • User messages and errors stay on .text().
  • Markdown styles are in Views/Report/TaskPane.cshtml.
  • Replies that built a report render as a result card with a "Report created" / "Report altered" header: WebClient AI pane UI.

Empty state​

  • Hero (✦ icon, title, subtitle) and three cards: Create, Alter, Insights.
  • Create and Alter cards send their localized example (data-prompt).
  • Insights card switches to the Insights tab.
  • Strings: 8 keys in WebClient/InsFocusBI.WebClient.Resources/Report/Report.resx and Report.he-il.resx. Old AiChatEmpty / AiChatStarter* keys are unused but kept.

Configuration​

  • Ai.IntentRouting — default true. false → legacy routing: no prior report → create, otherwise alter.
  • Ai.IntentModel — model for the router. Blank → Ai.Model. Passed as ChatOptions.ModelId per call.
  • Other Ai keys: Enabled, Provider, Model, ApiKey, StagedCreation, KnowledgeBaseMaxReports.
  • Fallback strings in the AI controller are inline English, not resx.
  • JS changes reach production only after the gulp asset build.

Decisions​

  • 2026-07-11 — Chat on an existing, already-run report alters it: the client sends its InputPaneParameters and the server reverse-maps them to GeneratedReport (was: first message always created a new report). Why: the alter prompt expects GeneratedReport JSON, which only existed for AI-built reports.
  • 2026-07-12 — Route every chat turn through an LLM intent router (NEW_REPORT, ALTER_REPORT_PARAMS, QUESTION, UNKNOWN) (was: first turn creates, later turns alter). Why: let the chatbot do more than create/alter.
  • 2026-07-12 — Router gets the current report as context. Why: better create vs alter accuracy.
  • 2026-07-12 — QUESTION answers are text only, grounded in the tenant semantic model.
  • 2026-07-12 — ALTER_REPORT_PARAMS with no open report asks for clarification.
  • 2026-07-12 — Router runs on a faster, cheaper model (Ai.IntentModel).
  • 2026-07-12 — Router failure falls back to state-based routing. Why: a bad IntentModel must not break report creation.
  • 2026-07-12 — Ai.IntentRouting kill switch keeps the legacy behavior available.
  • 2026-07-12 — New empty state: hero + Create / Alter / Insights cards (was: two starter pills).
  • 2026-07-12 — Render assistant markdown with an in-house escape-first renderer. Why: the app has no markdown or sanitizer library, and LLM output must not inject HTML.
  • 2026-07-12 — Conversation context: client-side history; the router rewrites each turn into ResolvedRequest; the QUESTION answerer also gets prior turns. Why: follow-ups like "yes" after "want me to build an example?" must resolve. History lives in one place and big prompts stay lean.

Gotchas​

  • Problem: New resx keys are not found at compile time on macOS. Fix: accessors live in the checked-in T4 output WebClient/InsFocusBI.WebClient.Resources/GenerateEnumFromResX.cs, which regenerates only in Visual Studio. Add the TranslationToken and _string properties to the Report class by hand.
  • Problem: dotnet build passes but a Razor view can still fail. Fix: views compile at runtime (no precompiled views). Check every resource key used in TaskPane.cshtml exists in both resx files and in GenerateEnumFromResX.cs.