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:
PushToBackForwardwith a server version bump. Every run (report, list, dashboard, single dashboard viewer) ends here.- End of
PopFromBackForward. Covers back/forward and Revert.
AiInsights.reportDataChangeddrops 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.csturns the open report into aReportDataPayload.ReportDataText.Renderturns the payload into the text sent to the gateway (ReportInsightsBL).ReportDataText.Valuewrites dates asyyyy-MM-dd, or ISO with time. Same on every server, whatever its locale.CellValuemaps each data cell type to a typed value:
| Cell type | Value sent |
|---|---|
TMEmptyCell, null | null |
| 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, TMDateTimeCell | The DateTime. null when unset (DateTime.MinValue). |
TMUrlCell | Display text, or the URL if display text is blank. |
TMTextCell | Text trimmed onto one line. null when blank. |
TMFlagCell | true / false. |
| Unknown cell type | Its own ToString() if overridden, otherwise null. |
ListValue(raw values in list reports):- Integer types and
decimalpass through. double,float:nullwhenNaNor infinite.bool,DateTimepass through.DateTime.MinValue→null.DateTimeOffset→ ISO text with offset.- Other types (
TimeSpan,Guid, enums) are formatted with invariant culture.
- Integer types and
- 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'sUserSettingsModel. MultiDimOutputGrid.GetFormattedNumericCell(row, col, gridProps, numberFormatter, theIgnoreScale)wraps the privateGetCellContents+GetItemIDused byWriteAsHtml. One place for the formatting rules.- No
GridPropertiesModel→ a default one, same asWriteAsText. BuildPayloadtakes an optionalUserSettingsModel 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, not56,800. - Other viewer settings still apply: currency symbol, thousands separator, percent, decimal digits.
theIgnoreScaledefaults to false. Grid, HTML and text exports are unchanged.- List reports and non-numeric cells are not formatted.
- Callers that pass preferences:
AiController.InsightsEstimateandReportInsights—[ModelBinder(typeof(UserPrefsModelBinder))] UserSettingsModel theUserPrefs.theReportInfouses[ModelBinder(typeof(ReportInfoModelBinder))].ScheduleRunner.PopulateInsights— its existingtheUserPreferences.
- 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 —
NaNand infinity are sent asnull. Why: not valid JSON numbers. - 2026-11-07 — Insights payload sends numeric cells formatted with the viewer's
GridPropertiesModeland 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(orTMTextCelletc.) instead of the value. Fix:TMDataCellsubclasses do not overrideToString().ReportDataBuilder.CellValuenow reads each cell type'sDataexplicitly. - Problem: Dates in list reports came out in the server locale's format (e.g.
07/11/2026 00:00:00). Fix:ListValuepassesDateTimethrough, soReportDataTextwrites it asyyyy-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:AiControllerhas[ApiController], which binds complex-type parameters from the body.ReportInfoandUserSettingsModelwere both inferred as body. Fix: name the custom binder on each parameter:[ModelBinder(typeof(ReportInfoModelBinder))]and[ModelBinder(typeof(UserPrefsModelBinder))](namespaceInsFocusBI.WebClient.General.ModelBinders).