@b2y/ai-service 0.0.0-stage → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +165 -2
- package/package.json +76 -4
- package/src/analytics/Analytics.js +584 -0
- package/src/analytics/Results.js +394 -0
- package/src/assistant/Assistant.js +452 -0
- package/src/assistant/Capabilities.js +344 -0
- package/src/constants/AnalyticsConstants.js +6 -0
- package/src/constants/AssistantConstants.js +5 -0
- package/src/constants/ConversationConstants.js +5 -0
- package/src/constants/DocumentConstants.js +4 -0
- package/src/constants/ProviderConstants.js +25 -0
- package/src/constants/ServerConstants.js +18 -0
- package/src/constants/SqlConstants.js +33 -0
- package/src/constants/UiConstants.js +29 -0
- package/src/conversations/ConversationHistory.js +149 -0
- package/src/conversations/FolderConversationStore.js +119 -0
- package/src/core/AiService.js +512 -0
- package/src/core/Context.js +243 -0
- package/src/core/Deadline.js +24 -0
- package/src/core/Errors.js +248 -0
- package/src/core/Tasks.js +190 -0
- package/src/documents/Documents.js +449 -0
- package/src/documents/FolderDocumentStore.js +167 -0
- package/src/documents/PdfText.js +50 -0
- package/src/enums/ChartType.js +1 -0
- package/src/enums/DataClassification.js +2 -0
- package/src/index.js +53 -0
- package/src/providers/Providers.js +475 -0
- package/src/server/Server.js +152 -0
- package/src/sql/PostgresSqlValidator.js +983 -0
- package/src/sql/SqlPolicy.js +483 -0
- package/src/ui/react/AssistantChat.js +594 -0
- package/src/ui/react/styles.css +239 -0
|
@@ -0,0 +1,394 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { CHART_TYPES } from "../enums/ChartType.js";
|
|
3
|
+
export { CHART_TYPES } from "../enums/ChartType.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Turns a checked query result into a chart specification the UI can draw: when the shape fits (one label
|
|
7
|
+
* column followed by 1-6 numeric columns), otherwise null and the caller shows a table.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
const MAX_POINTS = 36;
|
|
11
|
+
const MAX_SERIES = 6;
|
|
12
|
+
const MAX_PIE_SLICES = 8;
|
|
13
|
+
const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
|
|
14
|
+
const ISO_DAY = /^(\d{4})-(\d{2})-(\d{2})(?:[T ]|$)/;
|
|
15
|
+
|
|
16
|
+
export const chartSpecSchema = z
|
|
17
|
+
.strictObject({
|
|
18
|
+
chartType: z.enum(CHART_TYPES),
|
|
19
|
+
/** Types that suit this data, including chartType; the UI offers them as a switch. */
|
|
20
|
+
alternatives: z.array(z.enum(CHART_TYPES)).min(1).max(CHART_TYPES.length),
|
|
21
|
+
/** "table" when the user asked for tabular data; the chart is one click away. */
|
|
22
|
+
initialView: z.enum(["chart", "table"]),
|
|
23
|
+
title: z.string().min(1).max(120),
|
|
24
|
+
xLabels: z.array(z.string().min(1).max(40)).min(1).max(MAX_POINTS),
|
|
25
|
+
series: z
|
|
26
|
+
.array(z.strictObject({ name: z.string().min(1).max(60), values: z.array(z.number().finite().min(0)).min(1).max(MAX_POINTS) }))
|
|
27
|
+
.min(1)
|
|
28
|
+
.max(MAX_SERIES),
|
|
29
|
+
/** Which validated statements the numbers come from (sha256 fingerprints, never the SQL or values). */
|
|
30
|
+
basis: z.strictObject({
|
|
31
|
+
kind: z.literal("sql"),
|
|
32
|
+
fingerprints: z.array(z.string().regex(/^[0-9a-f]{64}$/)).min(1).max(4),
|
|
33
|
+
generatedAt: z.iso.datetime(),
|
|
34
|
+
}),
|
|
35
|
+
})
|
|
36
|
+
.superRefine((chart, ctx) => {
|
|
37
|
+
chart.series.forEach((series, index) => {
|
|
38
|
+
if (series.values.length !== chart.xLabels.length) ctx.addIssue({ code: "custom", path: ["series", index], message: "values must match xLabels" });
|
|
39
|
+
});
|
|
40
|
+
if ((chart.chartType === "doughnut" || chart.chartType === "pie") && chart.series.length !== 1) {
|
|
41
|
+
ctx.addIssue({ code: "custom", path: ["series"], message: "one series" });
|
|
42
|
+
}
|
|
43
|
+
if (!chart.alternatives.includes(chart.chartType)) ctx.addIssue({ code: "custom", path: ["alternatives"], message: "must include chartType" });
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
/** A cell as a number: numbers and numeric strings (PostgreSQL returns bigint and numeric as text). Null counts as 0. */
|
|
47
|
+
export function numericCell(cell) {
|
|
48
|
+
if (cell === null) return 0;
|
|
49
|
+
const value = typeof cell === "number" ? cell : typeof cell === "string" && /^-?\d+(\.\d+)?$/.test(cell) ? Number(cell) : NaN;
|
|
50
|
+
return Number.isFinite(value) ? value : undefined;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** Whether every cell is an ISO date (YYYY-MM-DD, optionally with a time). */
|
|
54
|
+
export function isDateColumn(cells) {
|
|
55
|
+
return cells.length > 0 && cells.every((cell) => typeof cell === "string" && ISO_DAY.test(cell));
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** Dates as "Jan 2026" when every label is the 1st of a month, otherwise "2 Jan 2026"; other text as is. */
|
|
59
|
+
export function formatLabels(cells, valueLabels = {}) {
|
|
60
|
+
if (isDateColumn(cells)) {
|
|
61
|
+
const days = cells.map((cell) => ISO_DAY.exec(cell));
|
|
62
|
+
const monthly = days.every((match) => match[3] === "01");
|
|
63
|
+
return { dates: true, labels: days.map(([, year, month, day]) => `${monthly ? "" : `${Number(day)} `}${MONTHS[Number(month) - 1]} ${year}`) };
|
|
64
|
+
}
|
|
65
|
+
return {
|
|
66
|
+
dates: false,
|
|
67
|
+
labels: cells.map((cell) => {
|
|
68
|
+
if (cell === null) return "(none)";
|
|
69
|
+
const text = String(cell);
|
|
70
|
+
return (Object.hasOwn(valueLabels, text) ? valueLabels[text] : text).slice(0, 40) || "(empty)";
|
|
71
|
+
}),
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* "Long" results (label, category, number), such as month / platform / count, become one row per label with a
|
|
77
|
+
* column per category (at most MAX_SERIES categories; missing combinations count as 0).
|
|
78
|
+
*/
|
|
79
|
+
function pivotLong(result) {
|
|
80
|
+
const { columns, rows } = result;
|
|
81
|
+
if (columns.length !== 3 || rows.length === 0) return result;
|
|
82
|
+
// The middle column must be a text category (not a number PostgreSQL returned as text).
|
|
83
|
+
if (!rows.every((row) => typeof row[1] === "string" && numericCell(row[1]) === undefined && numericCell(row[2]) !== undefined)) return result;
|
|
84
|
+
const categories = [...new Set(rows.map((row) => row[1]))];
|
|
85
|
+
if (categories.length < 2 || categories.length > MAX_SERIES) return result;
|
|
86
|
+
const byLabel = new Map();
|
|
87
|
+
for (const [label, category, value] of rows) {
|
|
88
|
+
const key = String(label);
|
|
89
|
+
if (!byLabel.has(key)) byLabel.set(key, { label, values: new Map() });
|
|
90
|
+
byLabel.get(key).values.set(category, numericCell(value));
|
|
91
|
+
}
|
|
92
|
+
return {
|
|
93
|
+
columns: [columns[0], ...categories.map((name) => ({ name }))],
|
|
94
|
+
rows: [...byLabel.values()].map(({ label, values }) => [label, ...categories.map((category) => values.get(category) ?? 0)]),
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/** One row of several numbers (for example count(*) FILTER per category) becomes one bar per column. */
|
|
99
|
+
function transposeSingleRow(result) {
|
|
100
|
+
const { columns, rows } = result;
|
|
101
|
+
if (rows.length !== 1 || columns.length < 2 || !rows[0].every((cell) => numericCell(cell) !== undefined)) return result;
|
|
102
|
+
return { columns: [{ name: "measure" }, { name: "value" }], rows: columns.map((column, index) => [column.name, numericCell(rows[0][index])]) };
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** Chart types that can show this data: pies need one series of at most 8 values, lines at least 2 points. */
|
|
106
|
+
function compatibleTypes(points, series) {
|
|
107
|
+
const types = ["bar", "horizontal_bar"];
|
|
108
|
+
if (series.length >= 2) types.push("stacked_bar");
|
|
109
|
+
if (points >= 2) types.push("line", "area");
|
|
110
|
+
if (series.length === 1 && points >= 2 && points <= MAX_PIE_SLICES && series[0].values.some((value) => value > 0)) types.push("pie", "doughnut");
|
|
111
|
+
return types;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** Without a requested type: lines for dates, horizontal bars for many or long labels, otherwise bars. */
|
|
115
|
+
function defaultType(x, alternatives) {
|
|
116
|
+
if (x.dates && alternatives.includes("line")) return "line";
|
|
117
|
+
if (x.labels.length > 12 || x.labels.some((label) => label.length > 14)) return "horizontal_bar";
|
|
118
|
+
return "bar";
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* A chart when the shape fits, or null. The hint picks the type when it suits the data, but a hint of
|
|
123
|
+
* "table" or "none" does not hide a chartable result; a single number is never charted.
|
|
124
|
+
* @param {{ columns: readonly { name: string }[], rows: readonly (readonly unknown[])[] }} result
|
|
125
|
+
* @param {{ chartHint?: string, title?: string, fingerprints: readonly string[], generatedAt?: string, labels?: Record<string, string>, valueLabels?: Record<string, string> }} options
|
|
126
|
+
*/
|
|
127
|
+
export function buildResultChart(result, { chartHint, title, fingerprints, generatedAt = new Date().toISOString(), labels = {}, valueLabels = {} }) {
|
|
128
|
+
const { columns, rows } = transposeSingleRow(pivotLong(result));
|
|
129
|
+
if (rows.length === 0 || rows.length > MAX_POINTS || (rows.length === 1 && columns.length < 2)) return null;
|
|
130
|
+
if (columns.length < 2 || columns.length - 1 > MAX_SERIES) return null;
|
|
131
|
+
const series = [];
|
|
132
|
+
for (let index = 1; index < columns.length; index += 1) {
|
|
133
|
+
const values = rows.map((row) => numericCell(row[index]));
|
|
134
|
+
if (values.some((value) => value === undefined || value < 0)) return null;
|
|
135
|
+
const name = columns[index].name;
|
|
136
|
+
series.push({ name: (labels[name] ?? valueLabels[name] ?? name).slice(0, 60), values });
|
|
137
|
+
}
|
|
138
|
+
const x = formatLabels(
|
|
139
|
+
rows.map((row) => row[0]),
|
|
140
|
+
valueLabels,
|
|
141
|
+
);
|
|
142
|
+
const alternatives = compatibleTypes(x.labels.length, series);
|
|
143
|
+
const chartType = alternatives.includes(chartHint) ? chartHint : defaultType(x, alternatives);
|
|
144
|
+
const parsed = chartSpecSchema.safeParse({
|
|
145
|
+
chartType,
|
|
146
|
+
alternatives,
|
|
147
|
+
initialView: chartHint === "table" ? "table" : "chart",
|
|
148
|
+
title: (title || "Statistics").slice(0, 120),
|
|
149
|
+
xLabels: x.labels,
|
|
150
|
+
series,
|
|
151
|
+
basis: { kind: "sql", fingerprints: [...fingerprints], generatedAt },
|
|
152
|
+
});
|
|
153
|
+
return parsed.success ? parsed.data : null;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/** Combines and describes checked query results in code. */
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* @typedef {Object} AnalyticsSection
|
|
160
|
+
* @property {string} id - "q1" or, for merged results, "q1+q2".
|
|
161
|
+
* @property {string} title
|
|
162
|
+
* @property {readonly string[]} queryIds - The planned queries the numbers come from.
|
|
163
|
+
* @property {readonly { name: string }[]} columns
|
|
164
|
+
* @property {readonly (readonly (string | number | boolean | null)[])[]} rows
|
|
165
|
+
* @property {boolean} truncated
|
|
166
|
+
*/
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* @typedef {Object} Evidence
|
|
170
|
+
* @property {readonly string[]} queryIds
|
|
171
|
+
* @property {string | null} label - The row label (category or period) the value belongs to, if any.
|
|
172
|
+
* @property {string} column
|
|
173
|
+
* @property {number} value
|
|
174
|
+
*/
|
|
175
|
+
|
|
176
|
+
/** @typedef {{ text: string, evidence: readonly Evidence[] }} Observation */
|
|
177
|
+
|
|
178
|
+
/** Which columns are numbers, and what kind of label column the section has (first column only). */
|
|
179
|
+
export function describeShape(section) {
|
|
180
|
+
const { columns, rows } = section;
|
|
181
|
+
const column = (index) => rows.map((row) => row[index]);
|
|
182
|
+
const numeric = (index) => rows.length > 0 && column(index).every((cell) => cell !== null && numericCell(cell) !== undefined);
|
|
183
|
+
const first = rows.length === 0 ? "none" : isDateColumn(column(0)) ? "date" : numeric(0) ? "number" : "category";
|
|
184
|
+
if (first === "number") return { label: "none", metrics: columns.map((_, index) => index) };
|
|
185
|
+
const metrics = [];
|
|
186
|
+
for (let index = 1; index < columns.length; index += 1) {
|
|
187
|
+
// Merged results may have gaps (null): a column with numbers and gaps still counts as a metric.
|
|
188
|
+
const cells = column(index);
|
|
189
|
+
if (cells.some((cell) => cell !== null) && cells.every((cell) => cell === null || numericCell(cell) !== undefined)) metrics.push(index);
|
|
190
|
+
}
|
|
191
|
+
return { label: first, metrics };
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
const isoKey = (cell) => (typeof cell === "string" ? cell.slice(0, 10) : String(cell));
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Lines up independent results that share a mergeKey: each must have that key as its first column and
|
|
198
|
+
* only numbers after it. Rows are matched on the key; a key missing from one result leaves null there.
|
|
199
|
+
* Results that cannot be lined up stay separate. Never touches SQL: merging happens after execution.
|
|
200
|
+
* @param {readonly (AnalyticsSection & { mergeKey: string })[]} sections - In plan order.
|
|
201
|
+
* @returns {AnalyticsSection[]}
|
|
202
|
+
*/
|
|
203
|
+
export function mergeSections(sections) {
|
|
204
|
+
const groups = new Map();
|
|
205
|
+
for (const section of sections) {
|
|
206
|
+
const key = section.mergeKey;
|
|
207
|
+
const mergeable =
|
|
208
|
+
key !== "" &&
|
|
209
|
+
section.columns.length >= 2 &&
|
|
210
|
+
section.columns[0].name === key &&
|
|
211
|
+
describeShape(section).metrics.length === section.columns.length - 1 &&
|
|
212
|
+
section.rows.length > 0;
|
|
213
|
+
if (!mergeable) continue;
|
|
214
|
+
if (!groups.has(key)) groups.set(key, []);
|
|
215
|
+
groups.get(key).push(section);
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
const merged = new Map();
|
|
219
|
+
for (const [key, members] of groups) {
|
|
220
|
+
if (members.length < 2) continue;
|
|
221
|
+
const dates = members.every((member) => isDateColumn(member.rows.map((row) => row[0])));
|
|
222
|
+
const order = [];
|
|
223
|
+
const seen = new Set();
|
|
224
|
+
for (const member of members) {
|
|
225
|
+
for (const row of member.rows) {
|
|
226
|
+
const id = dates ? isoKey(row[0]) : String(row[0]);
|
|
227
|
+
if (!seen.has(id)) {
|
|
228
|
+
seen.add(id);
|
|
229
|
+
order.push({ id, label: dates ? isoKey(row[0]) : row[0] });
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
if (dates) order.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
|
|
234
|
+
|
|
235
|
+
const names = new Set([key]);
|
|
236
|
+
const columns = [{ name: key }];
|
|
237
|
+
const lookups = [];
|
|
238
|
+
for (const member of members) {
|
|
239
|
+
const byKey = new Map(member.rows.map((row) => [dates ? isoKey(row[0]) : String(row[0]), row]));
|
|
240
|
+
for (let index = 1; index < member.columns.length; index += 1) {
|
|
241
|
+
let name = member.columns[index].name;
|
|
242
|
+
if (names.has(name)) name = `${name}_${member.id}`;
|
|
243
|
+
names.add(name);
|
|
244
|
+
columns.push({ name });
|
|
245
|
+
lookups.push({ byKey, index });
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
if (columns.length > 9) continue;
|
|
249
|
+
const rows = order.map(({ id, label }) => [label, ...lookups.map(({ byKey, index }) => (byKey.has(id) ? byKey.get(id)[index] : null))]);
|
|
250
|
+
merged.set(members[0].id, {
|
|
251
|
+
id: members.map((member) => member.id).join("+"),
|
|
252
|
+
title: members.map((member) => member.title).join(" and "),
|
|
253
|
+
queryIds: members.flatMap((member) => member.queryIds),
|
|
254
|
+
columns,
|
|
255
|
+
rows,
|
|
256
|
+
truncated: members.some((member) => member.truncated),
|
|
257
|
+
members,
|
|
258
|
+
});
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
const absorbed = new Set([...merged.values()].flatMap((section) => section.members.map((member) => member.id)));
|
|
262
|
+
const out = [];
|
|
263
|
+
for (const section of sections) {
|
|
264
|
+
if (merged.has(section.id)) {
|
|
265
|
+
const combined = { ...merged.get(section.id) };
|
|
266
|
+
delete combined.members;
|
|
267
|
+
out.push(combined);
|
|
268
|
+
} else if (!absorbed.has(section.id)) {
|
|
269
|
+
const plain = { ...section };
|
|
270
|
+
delete plain.mergeKey;
|
|
271
|
+
out.push(plain);
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
return out;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
function humanize(name, labels) {
|
|
278
|
+
if (Object.hasOwn(labels, name)) return labels[name];
|
|
279
|
+
const words = name.replace(/_/g, " ").trim();
|
|
280
|
+
return words.length === 0 ? name : words[0].toUpperCase() + words.slice(1);
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* Evidence-backed observations for one section: totals, the largest and smallest categories with their
|
|
285
|
+
* share, peaks and the latest change over time, gaps, truncation and small-number caution.
|
|
286
|
+
* @param {AnalyticsSection} section
|
|
287
|
+
* @param {{ labels?: Record<string, string>, valueLabels?: Record<string, string>, locale?: string, today?: string, smallSampleBelow?: number }} [options]
|
|
288
|
+
* @returns {Observation[]}
|
|
289
|
+
*/
|
|
290
|
+
export function observeSection(section, options = {}) {
|
|
291
|
+
const { labels = {}, valueLabels = {}, locale = "en-US", today, smallSampleBelow = 30 } = options;
|
|
292
|
+
const format = new Intl.NumberFormat(locale, { maximumFractionDigits: 2 });
|
|
293
|
+
const n = (value) => format.format(value);
|
|
294
|
+
const { columns, rows, queryIds } = section;
|
|
295
|
+
const shape = describeShape(section);
|
|
296
|
+
const out = [];
|
|
297
|
+
const evidence = (label, index, value) => ({ queryIds, label, column: columns[index].name, value });
|
|
298
|
+
|
|
299
|
+
if (rows.length === 0) return [{ text: `${section.title}: no matching data.`, evidence: [] }];
|
|
300
|
+
|
|
301
|
+
if (shape.label === "none") {
|
|
302
|
+
// One row of numbers: report each.
|
|
303
|
+
if (rows.length === 1) {
|
|
304
|
+
const parts = shape.metrics.map((index) => ({ index, value: numericCell(rows[0][index]) }));
|
|
305
|
+
out.push({
|
|
306
|
+
text: `${parts.map(({ index, value }) => `${humanize(columns[index].name, labels)}: ${n(value)}`).join("; ")}.`,
|
|
307
|
+
evidence: parts.map(({ index, value }) => evidence(null, index, value)),
|
|
308
|
+
});
|
|
309
|
+
}
|
|
310
|
+
return out;
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
const rawLabels = rows.map((row) => row[0]);
|
|
314
|
+
const shown = formatLabels(rawLabels, valueLabels).labels;
|
|
315
|
+
const rowKey = (row) => (shape.label === "date" ? isoKey(row[0]) : String(row[0]));
|
|
316
|
+
|
|
317
|
+
for (const index of shape.metrics) {
|
|
318
|
+
const metric = humanize(columns[index].name, labels);
|
|
319
|
+
const present = rows.map((row, at) => ({ at, value: row[index] === null ? null : numericCell(row[index]) }));
|
|
320
|
+
const values = present.filter((item) => item.value !== null);
|
|
321
|
+
if (values.length === 0) continue;
|
|
322
|
+
const total = values.reduce((sum, item) => sum + item.value, 0);
|
|
323
|
+
const metricLower = metric.toLowerCase();
|
|
324
|
+
|
|
325
|
+
if (shape.label === "category") {
|
|
326
|
+
out.push({
|
|
327
|
+
text: `${metric}: ${n(total)} in total across ${values.length} ${values.length === 1 ? "group" : "groups"}.`,
|
|
328
|
+
evidence: values.map(({ at, value }) => evidence(rowKey(rows[at]), index, value)),
|
|
329
|
+
});
|
|
330
|
+
if (values.length >= 2 && total > 0) {
|
|
331
|
+
const sorted = [...values].sort((a, b) => b.value - a.value);
|
|
332
|
+
const top = sorted[0];
|
|
333
|
+
const tied = sorted.filter((item) => item.value === top.value);
|
|
334
|
+
if (tied.length === 1) {
|
|
335
|
+
out.push({
|
|
336
|
+
text: `${shown[top.at]} has the most ${metricLower}: ${n(top.value)} (${Math.round((top.value / total) * 100)}% of ${n(total)}).`,
|
|
337
|
+
evidence: [evidence(rowKey(rows[top.at]), index, top.value)],
|
|
338
|
+
});
|
|
339
|
+
}
|
|
340
|
+
const low = sorted[sorted.length - 1];
|
|
341
|
+
if (values.length >= 3 && sorted.filter((item) => item.value === low.value).length === 1) {
|
|
342
|
+
out.push({ text: `${shown[low.at]} has the fewest: ${n(low.value)}.`, evidence: [evidence(rowKey(rows[low.at]), index, low.value)] });
|
|
343
|
+
}
|
|
344
|
+
}
|
|
345
|
+
} else {
|
|
346
|
+
// The range covers the periods that have a value: in merged results another metric may start earlier.
|
|
347
|
+
const first = shown[values[0].at];
|
|
348
|
+
const last = shown[values[values.length - 1].at];
|
|
349
|
+
out.push({
|
|
350
|
+
text: `${metric}: ${n(total)} in total ${first === last ? `in ${first}` : `from ${first} to ${last}`}.`,
|
|
351
|
+
evidence: values.map(({ at, value }) => evidence(rowKey(rows[at]), index, value)),
|
|
352
|
+
});
|
|
353
|
+
if (values.length >= 2) {
|
|
354
|
+
const peak = values.reduce((best, item) => (item.value > best.value ? item : best));
|
|
355
|
+
if (values.filter((item) => item.value === peak.value).length === 1) {
|
|
356
|
+
out.push({ text: `${metric} peaked in ${shown[peak.at]} (${n(peak.value)}).`, evidence: [evidence(rowKey(rows[peak.at]), index, peak.value)] });
|
|
357
|
+
}
|
|
358
|
+
const latest = values[values.length - 1];
|
|
359
|
+
const previous = values[values.length - 2];
|
|
360
|
+
const change =
|
|
361
|
+
previous.value === 0 ? "" : ` (${latest.value >= previous.value ? "+" : ""}${Math.round(((latest.value - previous.value) / previous.value) * 100)}%)`;
|
|
362
|
+
const inProgress = today !== undefined && periodContains(rowKey(rows[latest.at]), rows, today);
|
|
363
|
+
out.push({
|
|
364
|
+
text: `${metric}: ${n(latest.value)} in ${shown[latest.at]} compared with ${n(previous.value)} in ${shown[previous.at]}${change}${inProgress ? `; ${shown[latest.at]} is not over yet` : ""}.`,
|
|
365
|
+
evidence: [evidence(rowKey(rows[previous.at]), index, previous.value), evidence(rowKey(rows[latest.at]), index, latest.value)],
|
|
366
|
+
});
|
|
367
|
+
}
|
|
368
|
+
const gaps = present.filter((item) => item.value === null);
|
|
369
|
+
if (gaps.length > 0) {
|
|
370
|
+
out.push({ text: `No ${metricLower} recorded in ${gaps.map((item) => shown[item.at]).join(", ")}.`, evidence: [] });
|
|
371
|
+
}
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
if (Number.isInteger(total) && total > 0 && total < smallSampleBelow && index === shape.metrics[0]) {
|
|
375
|
+
out.push({
|
|
376
|
+
text: `These are small numbers (${n(total)} in total), so shares and changes can swing a lot.`,
|
|
377
|
+
evidence: [{ queryIds, label: null, column: columns[index].name, value: total }],
|
|
378
|
+
});
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
if (section.truncated) out.push({ text: `${section.title}: only the first ${n(rows.length)} rows were returned; totals cover those rows only.`, evidence: [] });
|
|
382
|
+
return out;
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
/** Whether today falls in the latest period. */
|
|
386
|
+
function periodContains(latestKey, rows, today) {
|
|
387
|
+
const keys = rows.map((row) => (typeof row[0] === "string" ? row[0].slice(0, 10) : ""));
|
|
388
|
+
if (keys.every((key) => key.slice(5) === "01-01")) return today.slice(0, 4) === latestKey.slice(0, 4);
|
|
389
|
+
if (keys.every((key) => key.slice(8) === "01")) return today.slice(0, 7) === latestKey.slice(0, 7);
|
|
390
|
+
const day = (key) => Date.parse(`${key}T00:00:00Z`);
|
|
391
|
+
const spacing = keys.length >= 2 ? day(keys[keys.length - 1]) - day(keys[keys.length - 2]) : 86_400_000;
|
|
392
|
+
const start = day(latestKey);
|
|
393
|
+
return day(today) >= start && day(today) < start + Math.max(spacing, 86_400_000);
|
|
394
|
+
}
|