@viccydev/pi-fpa 0.2.0

package/extensions/fpa-data/index.ts

@@ -0,0 +1,478 @@
+/**
+ * FP&A data extension: read-only Supabase mart access plus deterministic
+ * calculation tools.
+ *
+ * Design contract: the LLM never writes SQL and never performs arithmetic.
+ * It selects registered datasets/metrics/dimensions; SQL is generated and
+ * validated here, aggregation runs in Postgres, and every derived number
+ * (ratios, deltas, LTV/ROAS/retention, ad-hoc formulas) is computed in this
+ * extension with null-safe semantics.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+	buildCohortRows,
+	comparePeriods,
+	computeDerived,
+	round,
+	runCalc,
+	toNumber,
+	type CalcExpression,
+	type NumericLike,
+} from "./calc.ts";
+import { CATALOG_CAVEATS, DATASETS, DATASET_IDS } from "./registry.ts";
+import {
+	buildCohortQuery,
+	buildCoverageSql,
+	buildCohortSizeCoverageSql,
+	buildQuery,
+	MAX_LIMIT,
+	type QuerySpec,
+} from "./sql.ts";
+import { runQuery, type SqlRow } from "./supabase.ts";
+
+const MAX_TOOL_TEXT_CHARS = 100_000;
+const MAX_DISPLAY_ROWS = 200;
+
+const DatasetIdSchema = StringEnum(DATASET_IDS as [string, ...string[]], {
+	description: "Dataset id from fpa_data_catalog",
+});
+
+const ScalarSchema = Type.Union([Type.String(), Type.Number()]);
+const FiltersSchema = Type.Record(
+	Type.String({ minLength: 1 }),
+	Type.Union([ScalarSchema, Type.Array(ScalarSchema, { minItems: 1 })]),
+	{
+		description:
+			"Dimension filters. Different fields are AND; array values are OR. Use date_from/date_to for the date range.",
+	},
+);
+
+interface Presented {
+	text: string;
+	displayedRows?: number;
+	truncated: boolean;
+}
+
+function present(result: Record<string, unknown>, rowsKey = "rows"): Presented {
+	let displayed = result;
+	let displayedRows: number | undefined;
+	let truncated = false;
+
+	const rows = result[rowsKey];
+	if (Array.isArray(rows) && rows.length > MAX_DISPLAY_ROWS) {
+		displayedRows = MAX_DISPLAY_ROWS;
+		truncated = true;
+		displayed = {
+			...result,
+			[rowsKey]: rows.slice(0, MAX_DISPLAY_ROWS),
+			tool_output: {
+				truncated: true,
+				displayed_rows: MAX_DISPLAY_ROWS,
+				total_rows: rows.length,
+				hint: "Narrow filters or dimensions, or lower the limit.",
+			},
+		};
+	}
+
+	let text = JSON.stringify(displayed, null, 2);
+	while (text.length > MAX_TOOL_TEXT_CHARS) {
+		const currentRows = displayed[rowsKey];
+		if (!Array.isArray(currentRows) || currentRows.length <= 1) {
+			throw new Error(
+				`Result exceeds the ${MAX_TOOL_TEXT_CHARS}-character tool output limit. Narrow the query.`,
+			);
+		}
+		const next = Math.max(1, Math.floor(currentRows.length / 2));
+		displayedRows = next;
+		truncated = true;
+		displayed = {
+			...displayed,
+			[rowsKey]: currentRows.slice(0, next),
+			tool_output: {
+				truncated: true,
+				displayed_rows: next,
+				total_rows: Array.isArray(rows) ? rows.length : undefined,
+				hint: "Narrow filters or dimensions, or lower the limit.",
+			},
+		};
+		text = JSON.stringify(displayed, null, 2);
+	}
+
+	return { text, displayedRows, truncated };
+}
+
+function toolResult(result: Record<string, unknown>, rowsKey = "rows") {
+	const presented = present(result, rowsKey);
+	return {
+		content: [{ type: "text" as const, text: presented.text }],
+		details: {
+			displayedRows: presented.displayedRows,
+			truncated: presented.truncated,
+		},
+	};
+}
+
+function shapeQueryRows(
+	rows: SqlRow[],
+	measures: string[],
+	derived: ReturnType<typeof buildQuery>["derived"],
+): SqlRow[] {
+	return rows.map((row) => {
+		const shaped: SqlRow = { ...row };
+		for (const name of measures) {
+			shaped[name] = round(toNumber(row[name] as NumericLike));
+		}
+		shaped.source_rows = toNumber(row.source_rows as NumericLike);
+		return { ...shaped, ...computeDerived(row, derived) };
+	});
+}
+
+async function runStructuredQuery(spec: QuerySpec, signal?: AbortSignal) {
+	const built = buildQuery(spec);
+	const rows = await runQuery(built.sql, { signal });
+	return { built, rows: shapeQueryRows(rows, built.measures, built.derived) };
+}
+
+export default function fpaDataExtension(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "fpa_data_catalog",
+		label: "FP&A Data Catalog",
+		description:
+			"List the FP&A datasets, dimensions, metrics (with formulas and aggregation semantics), " +
+			"live date coverage per dataset, and known data caveats. Call this before the first " +
+			"fpa_query/fpa_cohort/fpa_compare of a session.",
+		promptSnippet: "List FP&A datasets, metrics, live coverage, and caveats",
+		promptGuidelines: [
+			"Call fpa_data_catalog before the first FP&A data query of a session and treat its coverage block as the authority on which periods are answerable.",
+		],
+		parameters: Type.Object(
+			{
+				include_apps: Type.Optional(
+					Type.Boolean({ description: "Also list distinct app codes (up to 200)." }),
+				),
+			},
+			{ additionalProperties: false },
+		),
+		executionMode: "parallel",
+		async execute(_toolCallId, params, signal) {
+			const [coverage, cohortSize, apps] = await Promise.all([
+				runQuery(buildCoverageSql(), { signal }),
+				runQuery(buildCohortSizeCoverageSql(), { signal }),
+				params.include_apps
+					? runQuery(
+							"select app_code, string_agg(distinct platform, ',' order by platform) as platforms " +
+								"from appsflyer_ua_campaign_daily where app_code is not null " +
+								"group by 1 order by 1 limit 200",
+							{ signal },
+						)
+					: Promise.resolve<SqlRow[]>([]),
+			]);
+
+			return toolResult(
+				{
+					datasets: DATASETS.map((d) => ({
+						id: d.id,
+						description: d.description,
+						date_column: d.dateColumn,
+						dimensions: d.dimensions.map((x) => ({ name: x.name, description: x.description })),
+						metrics: [
+							...d.measures.map((m) => ({ name: m.name, unit: m.unit, description: m.description })),
+							...d.derived.map((m) => ({
+								name: m.name,
+								unit: m.unit,
+								description: `${m.description} (computed by the extension, never by the model)`,
+							})),
+						],
+						notes: d.notes,
+					})),
+					coverage,
+					cohort_size_available: cohortSize[0] ?? null,
+					caveats: CATALOG_CAVEATS,
+					...(params.include_apps ? { apps } : {}),
+				},
+				"coverage",
+			);
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_query",
+		label: "FP&A Query",
+		description:
+			"Aggregate FP&A metrics from the Supabase mart. Pick a dataset, registered metrics, optional " +
+			"dimensions/time grain/filters and a date range; SQL generation, aggregation, and ratio " +
+			"computation are handled deterministically (ratios recomputed from aggregated components, " +
+			"NULL on missing data or zero denominators). Results include date_min/date_max/source_rows coverage columns.",
+		promptSnippet: "Aggregate FP&A metrics (spend, installs, revenue, CPI, ROAS inputs) from Supabase",
+		promptGuidelines: [
+			"Use fpa_query for every FP&A number; never estimate or hand-compute metrics from raw rows.",
+			"Report the date_min/date_max coverage returned by fpa_query alongside any number whose requested range exceeds the covered range.",
+		],
+		parameters: Type.Object(
+			{
+				dataset: DatasetIdSchema,
+				metrics: Type.Array(Type.String({ minLength: 1 }), {
+					minItems: 1,
+					description: "Registered measure or derived metric names for the dataset",
+				}),
+				dimensions: Type.Optional(
+					Type.Array(Type.String({ minLength: 1 }), { description: "Group-by dimensions" }),
+				),
+				time_grain: Type.Optional(
+					StringEnum(["day", "week", "month"] as const, {
+						description: "Optional time bucketing on the dataset's date column",
+					}),
+				),
+				date_from: Type.Optional(Type.String({ description: "Inclusive ISO date" })),
+				date_to: Type.Optional(Type.String({ description: "Inclusive ISO date" })),
+				filters: Type.Optional(FiltersSchema),
+				sort: Type.Optional(
+					Type.Object(
+						{
+							by: Type.String({ minLength: 1 }),
+							direction: Type.Optional(StringEnum(["asc", "desc"] as const)),
+						},
+						{ additionalProperties: false },
+					),
+				),
+				limit: Type.Optional(
+					Type.Integer({ minimum: 1, maximum: MAX_LIMIT, description: `Row limit (default 200, max ${MAX_LIMIT})` }),
+				),
+			},
+			{ additionalProperties: false },
+		),
+		executionMode: "parallel",
+		async execute(_toolCallId, params, signal) {
+			const { built, rows } = await runStructuredQuery(
+				{
+					dataset: params.dataset,
+					metrics: params.metrics,
+					dimensions: params.dimensions,
+					timeGrain: params.time_grain,
+					dateFrom: params.date_from,
+					dateTo: params.date_to,
+					filters: params.filters,
+					sort: params.sort,
+					limit: params.limit,
+				},
+				signal,
+			);
+			return toolResult({
+				dataset: built.dataset.id,
+				rows,
+				row_count: rows.length,
+				notes: built.notes,
+				sql: built.sql,
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_cohort",
+		label: "FP&A Cohort Analysis",
+		description:
+			"Install-cohort LTV, ROAS, and retention curves per horizon (D0/D3/D7/...). Revenue is " +
+			"accumulated per install cohort in SQL, spend is joined from the UA table, and all ratios are " +
+			"computed deterministically. Immature horizons and cohorts without a recorded size return NULL " +
+			"with an explicit reason, never a guessed value.",
+		promptSnippet: "Compute install-cohort LTV / ROAS / retention curves",
+		promptGuidelines: [
+			"Use fpa_cohort (not fpa_query) for any LTV, ROAS, retention, or payback question; treat its NULL-with-reason entries as unanswerable rather than approximating them.",
+		],
+		parameters: Type.Object(
+			{
+				app_codes: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { minItems: 1 })),
+				platforms: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { minItems: 1 })),
+				install_from: Type.String({ description: "Inclusive ISO install-date start" }),
+				install_to: Type.String({ description: "Inclusive ISO install-date end" }),
+				horizons: Type.Optional(
+					Type.Array(Type.Integer({ minimum: 0, maximum: 365 }), {
+						minItems: 1,
+						description: "Days since install (default [0,3,7,14,30])",
+					}),
+				),
+				bucket: Type.Optional(
+					StringEnum(["day", "week", "month", "total"] as const, {
+						description: "Install-date bucketing (default week)",
+					}),
+				),
+				group_by: Type.Optional(
+					Type.Array(StringEnum(["app_code", "platform"] as const), {
+						description: "Grouping keys (default app_code + platform)",
+					}),
+				),
+			},
+			{ additionalProperties: false },
+		),
+		executionMode: "parallel",
+		async execute(_toolCallId, params, signal) {
+			const built = buildCohortQuery({
+				appCodes: params.app_codes,
+				platforms: params.platforms,
+				installFrom: params.install_from,
+				installTo: params.install_to,
+				horizons: params.horizons,
+				bucket: params.bucket,
+				groupBy: params.group_by,
+			});
+			const [cohortRows, spendRows, asOfRows] = await Promise.all([
+				runQuery(built.sql, { signal }),
+				runQuery(built.spendSql, { signal }),
+				runQuery(built.asOfSql, { signal }),
+			]);
+			const maxEventDate = (asOfRows[0]?.max_event_date as string | undefined) ?? null;
+			const minEventDate = (asOfRows[0]?.min_event_date as string | undefined) ?? null;
+			const rows = buildCohortRows(
+				cohortRows,
+				spendRows,
+				built.groupBy,
+				built.horizons,
+				maxEventDate,
+				minEventDate,
+			);
+			return toolResult({
+				bucket: built.bucket,
+				horizons: built.horizons,
+				data_as_of: asOfRows[0] ?? null,
+				rows,
+				row_count: rows.length,
+				notes: [
+					"Spend joined from appsflyer_ua_campaign_daily (breakdown_type=CAMPAIGN); ROAS is NULL where spend is absent.",
+					"LTV and retention use installed_user_count as the denominator and are NULL when the cohort size is unrecorded.",
+					"The source table is a rolling activity window: cohorts installed before its min event_date get NULL horizon metrics because their early revenue is not in the table.",
+				],
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_calc",
+		label: "FP&A Calculator",
+		description:
+			"Deterministic calculator for FP&A arithmetic: evaluate named formulas (+, -, *, /, parentheses, " +
+			"abs/min/max/round) against named numeric inputs. NULL inputs and division by zero propagate as " +
+			"NULL. Later expressions can reference earlier results. Runs locally; no database access.",
+		promptSnippet: "Evaluate FP&A formulas deterministically (never do mental math)",
+		promptGuidelines: [
+			"Route every ad-hoc calculation (variance, growth, run-rate, budget splits) through fpa_calc instead of computing it in prose.",
+		],
+		parameters: Type.Object(
+			{
+				values: Type.Record(Type.String({ minLength: 1 }), Type.Union([Type.Number(), Type.Null()]), {
+					description: "Named numeric inputs, e.g. from fpa_query results",
+				}),
+				expressions: Type.Array(
+					Type.Object(
+						{
+							name: Type.String({ minLength: 1, description: "Result name (valid identifier)" }),
+							formula: Type.String({ minLength: 1, description: "e.g. (actual - forecast) / abs(forecast)" }),
+						},
+						{ additionalProperties: false },
+					),
+					{ minItems: 1 },
+				),
+				precision: Type.Optional(
+					Type.Integer({ minimum: 0, maximum: 12, description: "Rounding precision (default 6)" }),
+				),
+			},
+			{ additionalProperties: false },
+		),
+		executionMode: "parallel",
+		async execute(_toolCallId, params) {
+			const results = runCalc(
+				params.values,
+				params.expressions as CalcExpression[],
+				params.precision ?? undefined,
+			);
+			return toolResult({ results }, "results");
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_compare",
+		label: "FP&A Period Compare",
+		description:
+			"Compare FP&A metrics between two periods (or actual vs. plan windows) on the same dataset. " +
+			"Runs both aggregations in SQL and computes per-row and total deltas, percentage changes, and " +
+			"per-row contribution to the total delta deterministically.",
+		promptSnippet: "Compare FP&A metrics across two periods with computed deltas",
+		promptGuidelines: [
+			"Use fpa_compare for period-over-period or actual-vs-baseline variance; do not subtract numbers from separate fpa_query calls manually.",
+		],
+		parameters: Type.Object(
+			{
+				dataset: DatasetIdSchema,
+				metrics: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+				dimensions: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+				filters: Type.Optional(FiltersSchema),
+				current: Type.Object(
+					{ from: Type.String(), to: Type.String() },
+					{ additionalProperties: false, description: "Current period (inclusive ISO dates)" },
+				),
+				baseline: Type.Object(
+					{ from: Type.String(), to: Type.String() },
+					{ additionalProperties: false, description: "Baseline period (inclusive ISO dates)" },
+				),
+				limit: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_LIMIT })),
+			},
+			{ additionalProperties: false },
+		),
+		executionMode: "parallel",
+		async execute(_toolCallId, params, signal) {
+			const dims = params.dimensions ?? [];
+			const makeSpec = (from: string, to: string, withDims: boolean): QuerySpec => ({
+				dataset: params.dataset,
+				metrics: params.metrics,
+				dimensions: withDims ? dims : [],
+				dateFrom: from,
+				dateTo: to,
+				filters: params.filters,
+				limit: params.limit,
+			});
+
+			const [current, baseline, currentTotal, baselineTotal] = await Promise.all([
+				runStructuredQuery(makeSpec(params.current.from, params.current.to, true), signal),
+				runStructuredQuery(makeSpec(params.baseline.from, params.baseline.to, true), signal),
+				dims.length > 0
+					? runStructuredQuery(makeSpec(params.current.from, params.current.to, false), signal)
+					: null,
+				dims.length > 0
+					? runStructuredQuery(makeSpec(params.baseline.from, params.baseline.to, false), signal)
+					: null,
+			]);
+
+			const baseMeasures = new Set(current.built.measures);
+			const rowComparisons = comparePeriods(
+				current.rows,
+				baseline.rows,
+				dims,
+				params.metrics,
+				baseMeasures,
+			);
+			const totals = comparePeriods(
+				(currentTotal ?? current).rows,
+				(baselineTotal ?? baseline).rows,
+				[],
+				params.metrics,
+				baseMeasures,
+			);
+
+			return toolResult({
+				dataset: params.dataset,
+				current_period: params.current,
+				baseline_period: params.baseline,
+				totals: totals[0] ?? null,
+				rows: rowComparisons,
+				row_count: rowComparisons.length,
+				notes: [
+					...current.built.notes,
+					"delta_pct is relative to abs(baseline); contribution_pct is each row's share of the total delta (base measures only).",
+				],
+			});
+		},
+	});
+}