Skip to main content

BI report generator and insights

Turns a natural-language question (Hebrew or English) into an InsFocusBI report definition (JSON). A second service surfaces insight cards from report results.

Architecture​

  • .NET BFF — entry point from the UI.
  • LangGraph (Python/FastAPI) — intent classification, report parameter generation, verification.
  • SSE — streams progress and results back.
  • Semantic model — time bases, items, dimensions, domains. Sent to the model as CSVs.

WebClient AI pane​

The legacy WebClient (InsFocusBI.WebClient) shows AI in the report right-side pane (DEV-731).

  • Pane — markup in Views/Report/TaskPane.cshtml. Two sub-views behind a segmented control (#reportAiTabs): Chat and Insights.
  • ReportTabManager.js — pane mode and sub-view (SetAiSubTab, ApplyReportPaneDefault).
  • AiInsights.js — Insights sub-view and its cost quote (api/Ai/InsightsEstimate).
  • Chat sub-view (intent routing, prompts, history): WebClient AI chat.
  • Styling, insight cards and grouping: WebClient AI pane UI.
  • Scripts are bundled by gulp in wwwroot. Rebuild the bundle after changes.

Dashboards​

  • Chat is not supported. IsAiChatSupportedForReport() returns false for dashboards.
  • The AI pane opens on Insights. The Chat/Insights switch is hidden.
  • The "Whole report" scope label is not shown. "Selected viewer" still shows for single-viewer insights.

Insights cost refresh​

  • The credit cost is re-quoted on every report data change.
  • Triggers:
    • PushToBackForward with a server version bump. Every run (report, list, dashboard, single dashboard viewer) ends here.
    • End of PopFromBackForward. Covers back/forward and Revert.
  • AiInsights.reportDataChanged drops the old quote and ignores in-flight requests for old data.
  • Insights tab selected: shows "Calculating cost…", disables Generate, re-quotes after a short debounce.
  • Other tab selected: no request. The quote is fetched when the user opens Insights.
  • Generate clicked before the new quote arrives: the user sees the new price and must click again.
  • Already generated insights stay on screen after a data change.

Insights report payload​

  • Server/InsFocusBI.Server.Data/BL/AI/ReportDataBuilder.cs turns the open report into a ReportDataPayload.
  • ReportDataText.Render turns the payload into the text sent to the gateway (ReportInsightsBL).
  • ReportDataText.Value writes dates as yyyy-MM-dd, or ISO with time. Same on every server, whatever its locale.
  • CellValue maps each data cell type to a typed value:
Cell typeValue sent
TMEmptyCell, nullnull
Numeric cells (count, monetary, rate, fixed rate, rank, quantitative)Formatted text when user preferences are given (e.g. ₪56,800.00, 12.5%). Otherwise the raw number. null when empty, NaN or infinite.
TMDateCell, TMDateTimeCellThe DateTime. null when unset (DateTime.MinValue).
TMUrlCellDisplay text, or the URL if display text is blank.
TMTextCellText trimmed onto one line. null when blank.
TMFlagCelltrue / false.
Unknown cell typeIts own ToString() if overridden, otherwise null.
  • ListValue (raw values in list reports):
    • Integer types and decimal pass through.
    • double, float: null when NaN or infinite.
    • bool, DateTime pass through. DateTime.MinValue → null.
    • DateTimeOffset → ISO text with offset.
    • Other types (TimeSpan, Guid, enums) are formatted with invariant culture.
  • Grid row and column headers use the header cell's ToString(). Header cell types override it.

Number formatting​

  • Numeric cells use the same formatting as the grid and the scheduled-report HTML.
  • Inputs: the viewer's GridPropertiesModel (with item-specific styles) and the user's UserSettingsModel.
  • MultiDimOutputGrid.GetFormattedNumericCell(row, col, gridProps, numberFormatter, theIgnoreScale) wraps the private GetCellContents + GetItemID used by WriteAsHtml. One place for the formatting rules.
  • No GridPropertiesModel → a default one, same as WriteAsText.
  • BuildPayload takes an optional UserSettingsModel userPreferences. No preferences → raw numbers.
  • Formatting throws → the cell falls back to the raw number.
  • Display scale (thousands, millions) is ignored. The AI path passes theIgnoreScale: true. Example: 56,800,000.00, not 56,800.
  • Other viewer settings still apply: currency symbol, thousands separator, percent, decimal digits.
  • theIgnoreScale defaults to false. Grid, HTML and text exports are unchanged.
  • List reports and non-numeric cells are not formatted.
  • Callers that pass preferences:
    • AiController.InsightsEstimate and ReportInsights — [ModelBinder(typeof(UserPrefsModelBinder))] UserSettingsModel theUserPrefs. theReportInfo uses [ModelBinder(typeof(ReportInfoModelBinder))].
    • ScheduleRunner.PopulateInsights — its existing theUserPreferences.
  • Tests: WebClient/InsFocusBI.WebClient.Tests/ReportDataBuilderTests.cs.

Configuration​

  • Dimension values are resolved through tool calls, never guessed.
  • Prompt includes axis placement rules.
  • Insights get a compact semantic context pack per tenant.

Decisions​

  • Backfill — Verify node is "cite, don't compute": the model cites numbers from results, never calculates them.
  • Backfill — Insights use a generate-then-verify loop.
  • Backfill — Pipeline: .NET BFF → LangGraph → SSE.
  • 2026-11-05 — WebClient AI pane: dashboards get Insights only, no Chat. Why: chat does not support dashboards yet.
  • 2026-11-05 — Insights credit cost refreshes on every report data change, including back/forward. Why: the price depends on the current data.
  • 2026-11-05 — No "Whole report" label for dashboard insights. Why: redundant.
  • 2026-11-07 — Insights payload maps every data cell type to a typed value (dates, flags, text, URLs, numbers). Why: non-numeric cells were sent as their class name.
  • 2026-11-07 — NaN and infinity are sent as null. Why: not valid JSON numbers.
  • 2026-11-07 — Insights payload sends numeric cells formatted with the viewer's GridPropertiesModel and the user's preferences (was: raw numbers). Why: match what the user sees in the grid.
  • 2026-11-07 — The AI payload ignores the thousands/millions display scale and sends full values. Why: a scaled number has no unit, so the AI cannot tell it is scaled.

Gotchas​

  • Problem: AI insights payload showed InsFocusBI.Business.TMDateCell (or TMTextCell etc.) instead of the value. Fix: TMDataCell subclasses do not override ToString(). ReportDataBuilder.CellValue now reads each cell type's Data explicitly.
  • Problem: Dates in list reports came out in the server locale's format (e.g. 07/11/2026 00:00:00). Fix: ListValue passes DateTime through, so ReportDataText writes it as yyyy-MM-dd.
  • Problem: WebClient failed at startup in MapControllers: "Action 'AiController.InsightsEstimate' has more than one parameter that was specified or inferred as bound from request body". Cause: AiController has [ApiController], which binds complex-type parameters from the body. ReportInfo and UserSettingsModel were both inferred as body. Fix: name the custom binder on each parameter: [ModelBinder(typeof(ReportInfoModelBinder))] and [ModelBinder(typeof(UserPrefsModelBinder))] (namespace InsFocusBI.WebClient.General.ModelBinders).