mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 07:13:29 +00:00
feat(insights): period-narrative summary on the overview
Add a calm "your week / month in review" summary to the Insights overview, generated from the period-narrative context (deltas, personal bands, FDR-controlled associations, coincident days). - New insight_narratives table (migration 0113): one durable row per (user, period, locale); generated prose AES-256-GCM at rest following the coach-message precedent; labels-only provenance stays plaintext. - generatePeriodNarrative feeds the context into the provider chain with a tight, descriptive-never-causal prompt; an insufficient context yields no narrative, a missing provider no-ops, neither fabricates. - Nightly warm cron on week (Mon) / month (1st) boundaries, budget-gated per user; the read-only GET enqueues a single-user warm on a cold read. - Read route is stale-while-revalidate and never blocks on the provider; the card renders plain text (no markdown), a single provenance disclosure, and a fixed footprint (no CLS). i18n in all six locales.
This commit is contained in:
1 parent
337f024a87
commit
5917bba61c
19 files changed
+1678
-2
No files matched your search
@@ -73,7 +73,6 @@
|
||||
"ignoreExportsUsedInFile": true,
|
||||
"ignoreIssues": {
|
||||
"src/components/ui/**": ["exports", "types"],
|
||||
"src/lib/validations/**": ["types"],
|
||||
"src/lib/insights/narrative/**": ["exports"]
|
||||
"src/lib/validations/**": ["types"]
|
||||
}
|
||||
}
|
||||
@@ -1540,6 +1540,16 @@
|
||||
"regenerateSuccess": "Analyse wurde neu erstellt",
|
||||
"warmAssessments": "Auswertungen vorbereiten",
|
||||
"warmStarted": "Auswertungen werden im Hintergrund erstellt",
|
||||
"narrativeTitle": "Dein Zeitraum im Rückblick",
|
||||
"narrativeWeek": "Diese Woche",
|
||||
"narrativeMonth": "Dieser Monat",
|
||||
"narrativePreparing": "Deine Zusammenfassung wird erstellt…",
|
||||
"narrativeUpdating": "Wird aktualisiert…",
|
||||
"narrativeUpdated": "Aktualisiert {time}",
|
||||
"narrativeProvenanceLabel": "Wie das zustande kam",
|
||||
"narrativeProvenanceMethod": "Eine Zusammenfassung des Zeitraums in einfacher Sprache, ausschließlich aus deinen erfassten Werten und den Zusammenhängen, die die statistische Mehrfachvergleichskorrektur überstanden haben. Beschreibend, nie eine Ursache.",
|
||||
"narrativeProvenanceMetrics": "Basierend auf: {metrics}",
|
||||
"narrativeProvenanceWindow": "Zeitfenster: {from} bis {to}",
|
||||
"heroFallbackSubtitle": "Täglicher Blick auf deine Trends — direkt aus den Zahlen, die du protokollierst.",
|
||||
"heroGreetingMorning": "Guten Morgen",
|
||||
"heroGreetingAfternoon": "Guten Tag",
|
||||
|
||||
@@ -1540,6 +1540,16 @@
|
||||
"regenerateSuccess": "Analysis refreshed",
|
||||
"warmAssessments": "Prepare assessments",
|
||||
"warmStarted": "Assessments are being prepared in the background",
|
||||
"narrativeTitle": "Your period in review",
|
||||
"narrativeWeek": "This week",
|
||||
"narrativeMonth": "This month",
|
||||
"narrativePreparing": "Preparing your summary…",
|
||||
"narrativeUpdating": "Updating…",
|
||||
"narrativeUpdated": "Updated {time}",
|
||||
"narrativeProvenanceLabel": "How this was put together",
|
||||
"narrativeProvenanceMethod": "A plain-language summary of the period, drawn only from your logged numbers and the associations that survived statistical multiple-comparison control. Descriptive, never a cause.",
|
||||
"narrativeProvenanceMetrics": "Based on: {metrics}",
|
||||
"narrativeProvenanceWindow": "Window: {from} to {to}",
|
||||
"heroFallbackSubtitle": "A daily read of your trends, drawn straight from the numbers you've logged.",
|
||||
"heroGreetingMorning": "Good morning",
|
||||
"heroGreetingAfternoon": "Good afternoon",
|
||||
|
||||
@@ -1540,6 +1540,16 @@
|
||||
"regenerateSuccess": "Análisis regenerado",
|
||||
"warmAssessments": "Preparar evaluaciones",
|
||||
"warmStarted": "Las evaluaciones se están preparando en segundo plano",
|
||||
"narrativeTitle": "Tu período en resumen",
|
||||
"narrativeWeek": "Esta semana",
|
||||
"narrativeMonth": "Este mes",
|
||||
"narrativePreparing": "Preparando tu resumen…",
|
||||
"narrativeUpdating": "Actualizando…",
|
||||
"narrativeUpdated": "Actualizado {time}",
|
||||
"narrativeProvenanceLabel": "Cómo se elaboró esto",
|
||||
"narrativeProvenanceMethod": "Un resumen del período en lenguaje sencillo, basado únicamente en tus valores registrados y en las asociaciones que superaron el control estadístico de comparaciones múltiples. Descriptivo, nunca una causa.",
|
||||
"narrativeProvenanceMetrics": "Basado en: {metrics}",
|
||||
"narrativeProvenanceWindow": "Ventana: del {from} al {to}",
|
||||
"heroFallbackSubtitle": "Una mirada diaria a tus tendencias — directamente de los datos que registras.",
|
||||
"heroGreetingMorning": "Buenos días",
|
||||
"heroGreetingAfternoon": "Buenas tardes",
|
||||
|
||||
@@ -1540,6 +1540,16 @@
|
||||
"regenerateSuccess": "Analyse regénérée",
|
||||
"warmAssessments": "Préparer les évaluations",
|
||||
"warmStarted": "Les évaluations sont en cours de préparation en arrière-plan",
|
||||
"narrativeTitle": "Votre période en revue",
|
||||
"narrativeWeek": "Cette semaine",
|
||||
"narrativeMonth": "Ce mois-ci",
|
||||
"narrativePreparing": "Préparation de votre résumé…",
|
||||
"narrativeUpdating": "Mise à jour…",
|
||||
"narrativeUpdated": "Mis à jour {time}",
|
||||
"narrativeProvenanceLabel": "Comment cela a été établi",
|
||||
"narrativeProvenanceMethod": "Un résumé de la période en langage clair, établi uniquement à partir de vos valeurs enregistrées et des associations ayant survécu au contrôle statistique des comparaisons multiples. Descriptif, jamais une cause.",
|
||||
"narrativeProvenanceMetrics": "Basé sur : {metrics}",
|
||||
"narrativeProvenanceWindow": "Fenêtre : du {from} au {to}",
|
||||
"heroFallbackSubtitle": "Un coup d’œil quotidien sur tes tendances — directement issu des chiffres que tu saisis.",
|
||||
"heroGreetingMorning": "Bonjour",
|
||||
"heroGreetingAfternoon": "Bonjour",
|
||||
|
||||
@@ -1540,6 +1540,16 @@
|
||||
"regenerateSuccess": "Analisi rigenerata",
|
||||
"warmAssessments": "Prepara le valutazioni",
|
||||
"warmStarted": "Le valutazioni vengono preparate in background",
|
||||
"narrativeTitle": "Il tuo periodo in sintesi",
|
||||
"narrativeWeek": "Questa settimana",
|
||||
"narrativeMonth": "Questo mese",
|
||||
"narrativePreparing": "Preparazione del riepilogo…",
|
||||
"narrativeUpdating": "Aggiornamento…",
|
||||
"narrativeUpdated": "Aggiornato {time}",
|
||||
"narrativeProvenanceLabel": "Come è stato realizzato",
|
||||
"narrativeProvenanceMethod": "Un riepilogo del periodo in linguaggio semplice, basato esclusivamente sui valori registrati e sulle associazioni che hanno superato il controllo statistico dei confronti multipli. Descrittivo, mai una causa.",
|
||||
"narrativeProvenanceMetrics": "Basato su: {metrics}",
|
||||
"narrativeProvenanceWindow": "Finestra: dal {from} al {to}",
|
||||
"heroFallbackSubtitle": "Uno sguardo quotidiano ai tuoi trend — direttamente dai numeri che registri.",
|
||||
"heroGreetingMorning": "Buongiorno",
|
||||
"heroGreetingAfternoon": "Buon pomeriggio",
|
||||
|
||||
@@ -1540,6 +1540,16 @@
|
||||
"regenerateSuccess": "Analiza wygenerowana ponownie",
|
||||
"warmAssessments": "Przygotuj analizy",
|
||||
"warmStarted": "Analizy są przygotowywane w tle",
|
||||
"narrativeTitle": "Twój okres w skrócie",
|
||||
"narrativeWeek": "Ten tydzień",
|
||||
"narrativeMonth": "Ten miesiąc",
|
||||
"narrativePreparing": "Przygotowywanie podsumowania…",
|
||||
"narrativeUpdating": "Aktualizowanie…",
|
||||
"narrativeUpdated": "Zaktualizowano {time}",
|
||||
"narrativeProvenanceLabel": "Jak to powstało",
|
||||
"narrativeProvenanceMethod": "Podsumowanie okresu w prostym języku, oparte wyłącznie na zarejestrowanych wartościach i powiązaniach, które przeszły statystyczną korektę dla porównań wielokrotnych. Opisowe, nigdy nie przyczynowe.",
|
||||
"narrativeProvenanceMetrics": "Na podstawie: {metrics}",
|
||||
"narrativeProvenanceWindow": "Okno: od {from} do {to}",
|
||||
"heroFallbackSubtitle": "Codzienne spojrzenie na twoje trendy — prosto z liczb, które rejestrujesz.",
|
||||
"heroGreetingMorning": "Dzień dobry",
|
||||
"heroGreetingAfternoon": "Dzień dobry",
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
-- v1.11.0 — period-narrative cache (Pillar P1).
|
||||
--
|
||||
-- One durable, typed row per (user, period, locale) holding the latest
|
||||
-- generated period summary ("how your week/month went"). Delete +
|
||||
-- regenerate clean: the unique index on (user_id, period, locale) enforces
|
||||
-- a single row per slot, so a regeneration upserts in place and there is
|
||||
-- never a stale duplicate to disambiguate.
|
||||
--
|
||||
-- The generated prose is held AES-256-GCM at rest in `encrypted_content`
|
||||
-- (BYTEA), following the `coach_messages.encrypted_content` precedent. The
|
||||
-- `provenance_json` envelope is labels-only (metric names, the read window,
|
||||
-- the FDR footer) and carries no PII, so it stays plaintext for a stable,
|
||||
-- queryable shape — matching `coach_messages.metric_source_json`.
|
||||
--
|
||||
-- Purely additive: one new table, no enum changes, no backfill. Deleting the
|
||||
-- user cascades every narrative away (clean GDPR-erasure).
|
||||
|
||||
CREATE TABLE IF NOT EXISTS "insight_narratives" (
|
||||
"id" TEXT NOT NULL,
|
||||
"user_id" TEXT NOT NULL,
|
||||
"period" TEXT NOT NULL,
|
||||
"locale" TEXT NOT NULL,
|
||||
"date_key" TEXT NOT NULL,
|
||||
"encrypted_content" BYTEA NOT NULL,
|
||||
"provenance_json" TEXT,
|
||||
"provider_type" TEXT,
|
||||
"prompt_version" TEXT,
|
||||
"created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"updated_at" TIMESTAMP(3) NOT NULL,
|
||||
|
||||
CONSTRAINT "insight_narratives_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS "insight_narratives_user_id_period_locale_key"
|
||||
ON "insight_narratives" ("user_id", "period", "locale");
|
||||
|
||||
CREATE INDEX IF NOT EXISTS "insight_narratives_user_id_updated_at_idx"
|
||||
ON "insight_narratives" ("user_id", "updated_at" DESC);
|
||||
|
||||
ALTER TABLE "insight_narratives"
|
||||
ADD CONSTRAINT "insight_narratives_user_id_fkey"
|
||||
FOREIGN KEY ("user_id") REFERENCES "users" ("id")
|
||||
ON DELETE CASCADE ON UPDATE CASCADE;
|
||||
@@ -428,6 +428,9 @@ model User {
|
||||
// provider chain entry) so a known-bad credential is negatively cached
|
||||
// across workers instead of re-burning a 401 every generation.
|
||||
providerHealth ProviderHealth[]
|
||||
// v1.11.0 W3 — one durable period-narrative row per (period, locale).
|
||||
// Delete/regenerate-clean; the generated prose is AES-256-GCM at rest.
|
||||
insightNarratives InsightNarrative[]
|
||||
|
||||
// v1.7.0 profile — optional patient-identity fields surfaced on the
|
||||
// health-record export cover (PDF) and the FHIR `Patient` resource.
|
||||
@@ -2830,3 +2833,49 @@ model ClinicianShareLink {
|
||||
@@index([expiresAt])
|
||||
@@map("clinician_share_links")
|
||||
}
|
||||
|
||||
// v1.11.0 W3 — period-narrative cache (Pillar P1).
|
||||
//
|
||||
// One durable, typed row per (user, period, locale) carrying the latest
|
||||
// generated period summary ("how your week/month went"). Delete +
|
||||
// regenerate clean: the unique constraint enforces a single row per slot,
|
||||
// so a regeneration upserts in place and there is never a stale duplicate
|
||||
// to disambiguate. The generated prose is held AES-256-GCM at rest in
|
||||
// `encryptedContent` (Bytes), following the `CoachMessage.encryptedContent`
|
||||
// precedent — the body is descriptive health narrative and is treated as
|
||||
// sensitive even though it carries labels-plus-numbers, not raw rows.
|
||||
//
|
||||
// `provenanceJson` is the labels-only provenance envelope the surface
|
||||
// renders as ⓘ chips (metric names + the read window + the FDR footer);
|
||||
// it carries no PII so it stays plaintext for a stable, queryable shape,
|
||||
// matching `CoachMessage.metricSourceJson`. `providerType` + `promptVersion`
|
||||
// mirror the attribution columns so the cross-feature aggregator can slice
|
||||
// quality per (provider × prompt). `period` is `week` | `month`; `dateKey`
|
||||
// is the UTC `YYYY-MM-DD` boundary the row was generated for, so the
|
||||
// stale-while-revalidate read can tell "today's" narrative from an older
|
||||
// one without decrypting.
|
||||
model InsightNarrative {
|
||||
id String @id @default(cuid())
|
||||
userId String @map("user_id")
|
||||
/// "week" | "month".
|
||||
period String
|
||||
/// Resolved UI locale of the prose ("de" | "en").
|
||||
locale String
|
||||
/// UTC YYYY-MM-DD boundary the narrative was generated for.
|
||||
dateKey String @map("date_key")
|
||||
/// AES-256-GCM ciphertext of the generated narrative prose.
|
||||
encryptedContent Bytes @map("encrypted_content")
|
||||
/// Labels-only provenance envelope (metric names, window, FDR footer).
|
||||
provenanceJson String? @map("provenance_json")
|
||||
providerType String? @map("provider_type")
|
||||
promptVersion String? @map("prompt_version")
|
||||
createdAt DateTime @default(now()) @map("created_at")
|
||||
updatedAt DateTime @updatedAt @map("updated_at")
|
||||
|
||||
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
||||
|
||||
// One row per (user, period, locale) — regeneration upserts in place.
|
||||
@@unique([userId, period, locale])
|
||||
@@index([userId, updatedAt(sort: Desc)])
|
||||
@@map("insight_narratives")
|
||||
}
|
||||
@@ -0,0 +1,95 @@
|
||||
/**
|
||||
* v1.11.0 W3 — period-narrative read route (Pillar P1).
|
||||
*
|
||||
* `GET /api/insights/narrative?period=week|month` serves the latest generated
|
||||
* period summary for the calling user. Read-only by construction (the v1.8.3
|
||||
* freeze posture): it NEVER blocks on the provider. It returns the last good
|
||||
* narrative immediately (stale-while-revalidate) and, when the row is missing
|
||||
* or stale and a provider is configured, fire-and-forget enqueues a warm so
|
||||
* the next read reflects the latest period.
|
||||
*
|
||||
* `userId` is narrowed from the session/Bearer (never a query field); an
|
||||
* unknown `period` 422s via the closed enum.
|
||||
*/
|
||||
import { NextRequest } from "next/server";
|
||||
import { z } from "zod/v4";
|
||||
import { apiSuccess, returnAllZodIssues } from "@/lib/api-response";
|
||||
import { apiHandler, requireAuth } from "@/lib/api-handler";
|
||||
import { annotate } from "@/lib/logging/context";
|
||||
import { resolveServerLocale } from "@/lib/i18n/server-locale";
|
||||
import { requireAssistantSurface } from "@/lib/feature-flags";
|
||||
import { hasUsableStatusProvider } from "@/lib/insights/status-provider";
|
||||
import { readPeriodNarrative } from "@/lib/insights/narrative/period-narrative-generate";
|
||||
import { PERIOD_DAYS, type NarrativePeriod } from "@/lib/insights/narrative/period-narrative";
|
||||
import { enqueueNarrativeWarm } from "@/lib/jobs/period-narrative-shared";
|
||||
|
||||
export const dynamic = "force-dynamic";
|
||||
|
||||
const NARRATIVE_PERIODS = Object.keys(PERIOD_DAYS) as [string, ...string[]];
|
||||
|
||||
const narrativeQuerySchema = z.object({
|
||||
period: z.enum(NARRATIVE_PERIODS),
|
||||
});
|
||||
|
||||
/** A narrative read this recently is considered fresh; no warm is enqueued. */
|
||||
const NARRATIVE_FRESH_MS = 20 * 60 * 60 * 1000;
|
||||
|
||||
function narrowLocale(locale: string): "de" | "en" {
|
||||
return locale === "en" ? "en" : "de";
|
||||
}
|
||||
|
||||
export const GET = apiHandler(async (request: NextRequest) => {
|
||||
const { user } = await requireAuth();
|
||||
await requireAssistantSurface("insightStatus");
|
||||
|
||||
const parsed = narrativeQuerySchema.safeParse({
|
||||
period: request.nextUrl.searchParams.get("period"),
|
||||
});
|
||||
if (!parsed.success) {
|
||||
annotate({
|
||||
action: { name: "insights.narrative.invalid-period" },
|
||||
meta: { issue_count: parsed.error.issues.length },
|
||||
});
|
||||
return returnAllZodIssues(parsed.error, 422);
|
||||
}
|
||||
const period = parsed.data.period as NarrativePeriod;
|
||||
|
||||
const resolved = await resolveServerLocale({
|
||||
request,
|
||||
userLocale: user.locale ?? null,
|
||||
override: request.nextUrl.searchParams.get("locale"),
|
||||
});
|
||||
const locale = narrowLocale(resolved);
|
||||
|
||||
const existing = await readPeriodNarrative(user.id, period, locale);
|
||||
const isFresh =
|
||||
existing !== null &&
|
||||
Date.now() - new Date(existing.updatedAt).getTime() < NARRATIVE_FRESH_MS;
|
||||
|
||||
// Read-only: never block on the provider. Warm out of band only when stale
|
||||
// / missing AND a provider is configured (a provider-less account costs one
|
||||
// cheap chain-resolve and shows the no-key state instead).
|
||||
let revalidating = false;
|
||||
if (!isFresh && (await hasUsableStatusProvider(user.id))) {
|
||||
void enqueueNarrativeWarm({ userId: user.id, period, locale });
|
||||
revalidating = true;
|
||||
}
|
||||
|
||||
annotate({
|
||||
action: { name: "insights.narrative" },
|
||||
meta: { period, has_narrative: existing !== null, revalidating },
|
||||
});
|
||||
|
||||
return apiSuccess({
|
||||
period,
|
||||
locale,
|
||||
narrative: existing
|
||||
? {
|
||||
text: existing.text,
|
||||
provenance: existing.provenance,
|
||||
updatedAt: existing.updatedAt,
|
||||
}
|
||||
: null,
|
||||
revalidating,
|
||||
});
|
||||
});
|
||||
@@ -120,6 +120,27 @@ const CoincidentDeviationCard = dynamic(
|
||||
},
|
||||
);
|
||||
|
||||
// v1.11.0 — period-narrative card (Pillar P1). The calm "your week/month in
|
||||
// review" summary, drawn from the read-only stale-while-revalidate narrative
|
||||
// route. Deferred behind `next/dynamic` like the other below-the-hero blocks;
|
||||
// it owns its own query and un-mounts when no narrative exists. The loader
|
||||
// skeleton shares the card's `min-h-40` footprint so the page does not shift.
|
||||
const PeriodNarrativeCard = dynamic(
|
||||
() =>
|
||||
import("@/components/insights/period-narrative-card").then((mod) => ({
|
||||
default: mod.PeriodNarrativeCard,
|
||||
})),
|
||||
{
|
||||
ssr: false,
|
||||
loading: () => (
|
||||
<div
|
||||
aria-hidden="true"
|
||||
className="bg-card border-border min-h-40 animate-pulse rounded-xl border motion-reduce:animate-none"
|
||||
/>
|
||||
),
|
||||
},
|
||||
);
|
||||
|
||||
/**
|
||||
* v1.4.25 W4d — Insights mother page.
|
||||
*
|
||||
@@ -270,6 +291,8 @@ export default function InsightsPage() {
|
||||
|
||||
<CoincidentDeviationCard enabled={isAuthenticated} />
|
||||
|
||||
{flags.briefing && <PeriodNarrativeCard enabled={isAuthenticated} />}
|
||||
|
||||
<div className="flex justify-end">
|
||||
<Button
|
||||
size="sm"
|
||||
|
||||
@@ -0,0 +1,212 @@
|
||||
"use client";
|
||||
|
||||
import { useState } from "react";
|
||||
import { useQuery } from "@tanstack/react-query";
|
||||
import { Info } from "lucide-react";
|
||||
|
||||
import { useTranslations } from "@/lib/i18n/context";
|
||||
import { queryKeys } from "@/lib/query-keys";
|
||||
import { cn } from "@/lib/utils";
|
||||
import {
|
||||
Popover,
|
||||
PopoverContent,
|
||||
PopoverTrigger,
|
||||
} from "@/components/ui/popover";
|
||||
|
||||
/**
|
||||
* v1.11.0 W3 — period-narrative card (Pillar P1).
|
||||
*
|
||||
* A calm, top-of-overview summary of the user's last week / month, drawn from
|
||||
* the read-only `GET /api/insights/narrative` route. The route is
|
||||
* stale-while-revalidate: it returns the last good prose instantly and warms a
|
||||
* fresh one out of band, so this card never blocks on the provider.
|
||||
*
|
||||
* Restraint guarantees: plain React text children (NO markdown — the whole
|
||||
* tree forbids a markdown library for XSS reasons), no score, no chart, a
|
||||
* single ⓘ provenance disclosure, and a fixed `min-h` footprint shared across
|
||||
* the loading / preparing / resolved states so the card — and everything below
|
||||
* it on the overview — never shifts (no CLS).
|
||||
*/
|
||||
|
||||
type NarrativePeriod = "week" | "month";
|
||||
|
||||
interface NarrativeProvenance {
|
||||
metrics: string[];
|
||||
window: { from: string; to: string };
|
||||
pairsTested: number;
|
||||
fdrQ: number;
|
||||
computedAt: string;
|
||||
}
|
||||
|
||||
interface NarrativeResponse {
|
||||
period: NarrativePeriod;
|
||||
locale: string;
|
||||
narrative: {
|
||||
text: string;
|
||||
provenance: NarrativeProvenance | null;
|
||||
updatedAt: string;
|
||||
} | null;
|
||||
revalidating: boolean;
|
||||
}
|
||||
|
||||
interface PeriodNarrativeCardProps {
|
||||
/** Gate the underlying read (e.g. on the auth flag). */
|
||||
enabled?: boolean;
|
||||
className?: string;
|
||||
}
|
||||
|
||||
async function fetchNarrative(
|
||||
period: NarrativePeriod,
|
||||
): Promise<NarrativeResponse> {
|
||||
const res = await fetch(`/api/insights/narrative?period=${period}`);
|
||||
if (!res.ok) {
|
||||
throw new Error(`narrative ${res.status}`);
|
||||
}
|
||||
return (await res.json()).data as NarrativeResponse;
|
||||
}
|
||||
|
||||
function ProvenanceDisclosure({
|
||||
provenance,
|
||||
}: {
|
||||
provenance: NarrativeProvenance;
|
||||
}) {
|
||||
const { t } = useTranslations();
|
||||
const metrics = provenance.metrics.slice(0, 8).join(", ");
|
||||
return (
|
||||
<Popover>
|
||||
<PopoverTrigger
|
||||
aria-label={t("insights.narrativeProvenanceLabel")}
|
||||
className="text-muted-foreground hover:text-foreground inline-flex size-5 shrink-0 items-center justify-center rounded-full transition-colors"
|
||||
>
|
||||
<Info className="size-3.5" aria-hidden="true" />
|
||||
</PopoverTrigger>
|
||||
<PopoverContent className="w-80 text-sm" align="end">
|
||||
<p className="text-foreground font-medium">
|
||||
{t("insights.narrativeProvenanceLabel")}
|
||||
</p>
|
||||
<p className="text-muted-foreground mt-1">
|
||||
{t("insights.narrativeProvenanceMethod")}
|
||||
</p>
|
||||
{metrics ? (
|
||||
<p className="text-muted-foreground mt-2 text-xs">
|
||||
{t("insights.narrativeProvenanceMetrics", { metrics })}
|
||||
</p>
|
||||
) : null}
|
||||
</PopoverContent>
|
||||
</Popover>
|
||||
);
|
||||
}
|
||||
|
||||
const SHELL =
|
||||
"bg-card border-border flex min-h-40 w-full min-w-0 flex-col gap-3 rounded-xl border p-4 md:p-6";
|
||||
|
||||
export function PeriodNarrativeCard({
|
||||
enabled = true,
|
||||
className,
|
||||
}: PeriodNarrativeCardProps) {
|
||||
const { t, locale } = useTranslations();
|
||||
const [period, setPeriod] = useState<NarrativePeriod>("week");
|
||||
|
||||
const query = useQuery({
|
||||
queryKey: queryKeys.insightsNarrative(period, locale),
|
||||
queryFn: () => fetchNarrative(period),
|
||||
enabled,
|
||||
// The route warms out of band; poll briefly while a refresh is in flight
|
||||
// so freshly-warmed prose lands without a manual remount.
|
||||
refetchInterval: (q) =>
|
||||
q.state.data?.revalidating && !q.state.data.narrative ? 5000 : false,
|
||||
});
|
||||
|
||||
// Loading with nothing to show yet → matched skeleton (CLS-safe).
|
||||
if (query.isLoading) {
|
||||
return (
|
||||
<div
|
||||
data-slot="period-narrative-card-skeleton"
|
||||
aria-hidden="true"
|
||||
className={cn(SHELL, className)}
|
||||
>
|
||||
<div className="flex h-7 items-center justify-between gap-2">
|
||||
<div className="bg-muted/40 h-3 w-32 rounded" />
|
||||
<div className="bg-muted/40 size-5 rounded-full" />
|
||||
</div>
|
||||
<div className="bg-muted/40 h-4 w-full rounded" />
|
||||
<div className="bg-muted/40 h-4 w-5/6 rounded" />
|
||||
<div className="bg-muted/40 h-4 w-2/3 rounded" />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// The route never errors the page; on a fetch error or a genuinely empty
|
||||
// account (no narrative ever produced) the card un-mounts itself rather than
|
||||
// showing an error or an empty husk on the overview.
|
||||
if (query.isError || (!query.data?.narrative && !query.data?.revalidating)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const data = query.data;
|
||||
const narrative = data?.narrative ?? null;
|
||||
const preparing = !narrative && data?.revalidating === true;
|
||||
|
||||
return (
|
||||
<div
|
||||
data-slot="period-narrative-card"
|
||||
data-period={period}
|
||||
className={cn(SHELL, className)}
|
||||
>
|
||||
<div className="flex items-center justify-between gap-2">
|
||||
<span className="text-muted-foreground truncate text-xs font-medium tracking-wide uppercase">
|
||||
{t("insights.narrativeTitle")}
|
||||
</span>
|
||||
{narrative?.provenance ? (
|
||||
<ProvenanceDisclosure provenance={narrative.provenance} />
|
||||
) : null}
|
||||
</div>
|
||||
|
||||
{/* Week / month toggle. Calm segmented control, no chart. */}
|
||||
<div className="flex gap-1 self-start" role="tablist">
|
||||
{(["week", "month"] as const).map((p) => (
|
||||
<button
|
||||
key={p}
|
||||
type="button"
|
||||
role="tab"
|
||||
aria-selected={period === p}
|
||||
onClick={() => setPeriod(p)}
|
||||
className={cn(
|
||||
"rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
|
||||
period === p
|
||||
? "bg-muted text-foreground"
|
||||
: "text-muted-foreground hover:text-foreground",
|
||||
)}
|
||||
>
|
||||
{p === "week"
|
||||
? t("insights.narrativeWeek")
|
||||
: t("insights.narrativeMonth")}
|
||||
</button>
|
||||
))}
|
||||
</div>
|
||||
|
||||
{preparing ? (
|
||||
<p className="text-muted-foreground text-sm">
|
||||
{t("insights.narrativePreparing")}
|
||||
</p>
|
||||
) : (
|
||||
// Plain text child — NO markdown renderer (XSS posture, CLAUDE.md).
|
||||
<p className="text-foreground text-sm leading-relaxed whitespace-pre-line">
|
||||
{narrative?.text}
|
||||
</p>
|
||||
)}
|
||||
|
||||
{narrative ? (
|
||||
<p className="text-muted-foreground mt-auto text-[11px]">
|
||||
{data?.revalidating
|
||||
? t("insights.narrativeUpdating")
|
||||
: t("insights.narrativeUpdated", {
|
||||
time: new Date(narrative.updatedAt).toLocaleDateString(
|
||||
locale === "de" ? "de-DE" : undefined,
|
||||
),
|
||||
})}
|
||||
</p>
|
||||
) : null}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,274 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
|
||||
// Identity "encryption" so the test asserts on plaintext round-trips without
|
||||
// an ENCRYPTION_KEYS env. The generator's `encryptToBytes`/`decryptFromBytes`
|
||||
// wrap these.
|
||||
vi.mock("@/lib/crypto", () => ({
|
||||
encrypt: (s: string) => `enc:${s}`,
|
||||
decrypt: (s: string) => s.replace(/^enc:/, ""),
|
||||
}));
|
||||
|
||||
// Keep the wide-event annotate a no-op.
|
||||
vi.mock("@/lib/logging/context", () => ({ annotate: vi.fn() }));
|
||||
|
||||
// The default DB import must resolve to something; every test injects its own
|
||||
// prisma double, so this is only a guard against accidental real-DB use.
|
||||
vi.mock("@/lib/db", () => ({ prisma: {} }));
|
||||
|
||||
import {
|
||||
generatePeriodNarrative,
|
||||
readPeriodNarrative,
|
||||
buildNarrativeUserPrompt,
|
||||
NARRATIVE_PROMPT_VERSION,
|
||||
} from "@/lib/insights/narrative/period-narrative-generate";
|
||||
import type {
|
||||
PeriodNarrativeContext,
|
||||
PeriodNarrativeResult,
|
||||
} from "@/lib/insights/narrative/period-narrative";
|
||||
|
||||
function readyContext(
|
||||
over: Partial<PeriodNarrativeContext> = {},
|
||||
): PeriodNarrativeContext {
|
||||
return {
|
||||
status: "ready",
|
||||
period: "week",
|
||||
metricDeltas: [
|
||||
{
|
||||
type: "WEIGHT",
|
||||
unit: "kg",
|
||||
current: 80,
|
||||
prior: 81,
|
||||
delta: -1,
|
||||
deltaPercent: -1.2,
|
||||
currentDays: 6,
|
||||
priorDays: 7,
|
||||
},
|
||||
],
|
||||
bandTransitions: [],
|
||||
drivers: [
|
||||
{
|
||||
behaviour: "ACTIVITY_STEPS",
|
||||
outcome: "SLEEP_DURATION",
|
||||
r: 0.4,
|
||||
qValue: 0.02,
|
||||
n: 14,
|
||||
interpretation: "more steps tended to coincide with longer sleep",
|
||||
},
|
||||
],
|
||||
coincidentFlags: [],
|
||||
pairsTested: 12,
|
||||
fdrQ: 0.1,
|
||||
provenance: {
|
||||
metrics: ["WEIGHT", "ACTIVITY_STEPS", "SLEEP_DURATION"],
|
||||
window: { from: "2026-05-01T00:00:00.000Z", to: "2026-05-15T00:00:00.000Z" },
|
||||
computedAt: "2026-05-15T05:00:00.000Z",
|
||||
},
|
||||
...over,
|
||||
};
|
||||
}
|
||||
|
||||
interface FakeRow {
|
||||
userId: string;
|
||||
period: string;
|
||||
locale: string;
|
||||
dateKey: string;
|
||||
encryptedContent: Uint8Array;
|
||||
provenanceJson: string | null;
|
||||
providerType: string | null;
|
||||
promptVersion: string | null;
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
/** Minimal in-memory prisma double for the (user, period, locale) row + user. */
|
||||
function makePrisma(seedRow?: FakeRow) {
|
||||
let row: FakeRow | undefined = seedRow;
|
||||
return {
|
||||
_get: () => row,
|
||||
user: {
|
||||
findUnique: vi.fn(async () => ({ timezone: "Europe/Berlin" })),
|
||||
},
|
||||
insightNarrative: {
|
||||
findUnique: vi.fn(async () => (row ? { ...row } : null)),
|
||||
upsert: vi.fn(async (args: { create: FakeRow; update: Partial<FakeRow> }) => {
|
||||
if (row) {
|
||||
row = { ...row, ...args.update, updatedAt: new Date() };
|
||||
} else {
|
||||
row = { ...args.create, updatedAt: new Date() };
|
||||
}
|
||||
return { ...row };
|
||||
}),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
beforeEach(() => vi.clearAllMocks());
|
||||
|
||||
describe("buildNarrativeUserPrompt", () => {
|
||||
it("renders metrics, drivers, and the FDR footer with the prompt version", () => {
|
||||
const prompt = buildNarrativeUserPrompt(readyContext(), "en");
|
||||
expect(prompt).toContain("WEIGHT");
|
||||
expect(prompt).toContain("ACTIVITY_STEPS ~ SLEEP_DURATION");
|
||||
expect(prompt).toContain("12 pairs tested");
|
||||
expect(NARRATIVE_PROMPT_VERSION).toBe("1.11.0");
|
||||
});
|
||||
});
|
||||
|
||||
describe("generatePeriodNarrative — descriptive generation", () => {
|
||||
it("generates a narrative from a seeded ready context and stores it encrypted", async () => {
|
||||
const prisma = makePrisma();
|
||||
const runCompletion = vi.fn(async () => ({
|
||||
kind: "ok" as const,
|
||||
content: "Your weight eased down slightly this week.",
|
||||
providerType: "openai",
|
||||
model: "gpt",
|
||||
tokensUsed: 50,
|
||||
}));
|
||||
const outcome = await generatePeriodNarrative("u1", {
|
||||
period: "week",
|
||||
locale: "en",
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
prisma: prisma as any,
|
||||
buildContext: async () => readyContext() as PeriodNarrativeResult,
|
||||
runCompletion,
|
||||
});
|
||||
expect(outcome).toEqual({ status: "generated", providerType: "openai" });
|
||||
expect(prisma.insightNarrative.upsert).toHaveBeenCalledOnce();
|
||||
const stored = prisma._get();
|
||||
expect(stored?.promptVersion).toBe(NARRATIVE_PROMPT_VERSION);
|
||||
// Stored ciphertext is the identity-encoded prose, not plaintext.
|
||||
expect(Buffer.from(stored!.encryptedContent).toString("utf8")).toBe(
|
||||
"enc:Your weight eased down slightly this week.",
|
||||
);
|
||||
});
|
||||
|
||||
it("passes a descriptive-never-causal system prompt to the provider", async () => {
|
||||
const prisma = makePrisma();
|
||||
let systemPrompt = "";
|
||||
const runCompletion = vi.fn(async (args: { systemPrompt: string }) => {
|
||||
systemPrompt = args.systemPrompt;
|
||||
return {
|
||||
kind: "ok" as const,
|
||||
content: "ok",
|
||||
providerType: "openai",
|
||||
model: "m",
|
||||
tokensUsed: 1,
|
||||
};
|
||||
});
|
||||
await generatePeriodNarrative("u1", {
|
||||
period: "week",
|
||||
locale: "en",
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
prisma: prisma as any,
|
||||
buildContext: async () => readyContext() as PeriodNarrativeResult,
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
runCompletion: runCompletion as any,
|
||||
});
|
||||
expect(systemPrompt).toMatch(/never CAUSAL|DESCRIPTIVE/);
|
||||
expect(systemPrompt).toMatch(/no markdown/i);
|
||||
});
|
||||
});
|
||||
|
||||
describe("generatePeriodNarrative — honesty floor", () => {
|
||||
it("writes no narrative when the context is insufficient", async () => {
|
||||
const prisma = makePrisma();
|
||||
const runCompletion = vi.fn();
|
||||
const outcome = await generatePeriodNarrative("u1", {
|
||||
period: "week",
|
||||
locale: "en",
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
prisma: prisma as any,
|
||||
buildContext: async () =>
|
||||
({
|
||||
status: "insufficient",
|
||||
period: "week",
|
||||
reason: "not_enough_history",
|
||||
coverage: { metricsWithData: 1, required: 2 },
|
||||
}) as PeriodNarrativeResult,
|
||||
runCompletion,
|
||||
});
|
||||
expect(outcome).toEqual({ status: "insufficient" });
|
||||
expect(runCompletion).not.toHaveBeenCalled();
|
||||
expect(prisma.insightNarrative.upsert).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("no-ops without a provider and never fabricates a story", async () => {
|
||||
const prisma = makePrisma();
|
||||
const outcome = await generatePeriodNarrative("u1", {
|
||||
period: "week",
|
||||
locale: "en",
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
prisma: prisma as any,
|
||||
buildContext: async () => readyContext() as PeriodNarrativeResult,
|
||||
runCompletion: async () => ({ kind: "none" as const }),
|
||||
});
|
||||
expect(outcome).toEqual({ status: "skipped", reason: "no-provider" });
|
||||
expect(prisma.insightNarrative.upsert).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe("generatePeriodNarrative — cache + regenerate", () => {
|
||||
it("serves a recent row without regenerating", async () => {
|
||||
const prisma = makePrisma({
|
||||
userId: "u1",
|
||||
period: "week",
|
||||
locale: "en",
|
||||
dateKey: "2026-05-15",
|
||||
encryptedContent: new Uint8Array(Buffer.from("enc:old", "utf8")),
|
||||
provenanceJson: null,
|
||||
providerType: "openai",
|
||||
promptVersion: NARRATIVE_PROMPT_VERSION,
|
||||
updatedAt: new Date(),
|
||||
});
|
||||
const runCompletion = vi.fn();
|
||||
const outcome = await generatePeriodNarrative("u1", {
|
||||
period: "week",
|
||||
locale: "en",
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
prisma: prisma as any,
|
||||
buildContext: async () => readyContext() as PeriodNarrativeResult,
|
||||
runCompletion,
|
||||
});
|
||||
expect(outcome).toEqual({ status: "cached" });
|
||||
expect(runCompletion).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("force regenerates and upserts the single row in place", async () => {
|
||||
const prisma = makePrisma({
|
||||
userId: "u1",
|
||||
period: "week",
|
||||
locale: "en",
|
||||
dateKey: "2026-05-15",
|
||||
encryptedContent: new Uint8Array(Buffer.from("enc:old", "utf8")),
|
||||
provenanceJson: null,
|
||||
providerType: "openai",
|
||||
promptVersion: "0.0.0",
|
||||
updatedAt: new Date(),
|
||||
});
|
||||
const outcome = await generatePeriodNarrative("u1", {
|
||||
period: "week",
|
||||
locale: "en",
|
||||
force: true,
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
prisma: prisma as any,
|
||||
buildContext: async () => readyContext() as PeriodNarrativeResult,
|
||||
runCompletion: async () => ({
|
||||
kind: "ok" as const,
|
||||
content: "fresh",
|
||||
providerType: "anthropic",
|
||||
model: "m",
|
||||
tokensUsed: 2,
|
||||
}),
|
||||
});
|
||||
expect(outcome).toEqual({ status: "generated", providerType: "anthropic" });
|
||||
// Read back the decrypted prose via the public reader.
|
||||
const read = await readPeriodNarrative(
|
||||
"u1",
|
||||
"week",
|
||||
"en",
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
prisma as any,
|
||||
);
|
||||
expect(read?.text).toBe("fresh");
|
||||
expect(read?.providerType).toBe("anthropic");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,393 @@
|
||||
/**
|
||||
* v1.11.0 W3 — period-narrative GENERATOR (Pillar P1).
|
||||
*
|
||||
* A sibling of `generateComprehensiveInsight`: it feeds the W2
|
||||
* `buildPeriodNarrativeContext` output — a compact, provenance-carrying
|
||||
* `label + number + source` context — into the user's provider chain with a
|
||||
* TIGHT, descriptive-never-causal prompt and persists the generated prose in
|
||||
* the typed `insight_narratives` table (AES-256-GCM at rest).
|
||||
*
|
||||
* Honesty floor (inherited verbatim from the W1/W2 layers it consumes):
|
||||
* - The context is the only ground truth. The prompt forbids inventing any
|
||||
* number, trend, driver, or threshold not present in the context.
|
||||
* - Drivers are already BH-FDR survivors with conservative `interpretation`
|
||||
* strings; the narrative may restate them as associations, NEVER as
|
||||
* causes.
|
||||
* - An `insufficient` context (too little history) yields NO narrative — the
|
||||
* generator returns `{ status: "insufficient" }` and writes nothing, so a
|
||||
* sparse account never gets a fabricated story.
|
||||
* - No provider configured → `{ status: "skipped", reason: "no-provider" }`,
|
||||
* no LLM call. A provider timeout / error is non-fatal and writes nothing.
|
||||
*
|
||||
* Cache + stale-while-revalidate mirror the per-status assessments: a fresh
|
||||
* read serves today's row instantly; a regenerate upserts the single
|
||||
* (user, period, locale) row in place (delete/regenerate-clean by
|
||||
* construction — the unique index forbids duplicates).
|
||||
*/
|
||||
import type { PrismaClient } from "@/generated/prisma/client";
|
||||
import { prisma as defaultPrisma } from "@/lib/db";
|
||||
import { encrypt, decrypt } from "@/lib/crypto";
|
||||
import { getLocalDateParts } from "@/lib/timezone";
|
||||
import { annotate } from "@/lib/logging/context";
|
||||
import { runStatusCompletion } from "@/lib/insights/status-provider";
|
||||
import {
|
||||
buildPeriodNarrativeContext,
|
||||
type NarrativePeriod,
|
||||
type PeriodNarrativeContext,
|
||||
} from "@/lib/insights/narrative/period-narrative";
|
||||
|
||||
/**
|
||||
* Stable identifier for the narrative prompt revision. Bumped whenever the
|
||||
* prompt below changes so the cross-feature attribution aggregator can slice
|
||||
* quality per (provider × prompt) and a prompt change is observable.
|
||||
*/
|
||||
export const NARRATIVE_PROMPT_VERSION = "1.11.0" as const;
|
||||
|
||||
/** A narrative cached this recently is served without regenerating. */
|
||||
const NARRATIVE_FRESH_MS = 20 * 60 * 60 * 1000;
|
||||
|
||||
export type NarrativeGenerateOutcome =
|
||||
| { status: "cached" }
|
||||
| { status: "generated"; providerType: string }
|
||||
| { status: "skipped"; reason: "no-provider" }
|
||||
| { status: "insufficient" }
|
||||
| { status: "failed"; reason: string };
|
||||
|
||||
interface GenerateOptions {
|
||||
/** Which period to narrate. */
|
||||
period: NarrativePeriod;
|
||||
/** Resolved UI locale for the prompt + row. */
|
||||
locale: "de" | "en";
|
||||
/** Skip the freshness short-circuit and force a fresh generation. */
|
||||
force?: boolean;
|
||||
/** Injected clock for deterministic tests; defaults to now. */
|
||||
now?: Date;
|
||||
/** Injected for tests — defaults to the real DB context assembler. */
|
||||
buildContext?: typeof buildPeriodNarrativeContext;
|
||||
/** Injected for tests — defaults to the real bounded provider call. */
|
||||
runCompletion?: typeof runStatusCompletion;
|
||||
/** Injected for tests — the shared client by default. */
|
||||
prisma?: PrismaClient;
|
||||
}
|
||||
|
||||
/** The labels-only provenance the surface renders as ⓘ chips. */
|
||||
export interface NarrativeProvenancePayload {
|
||||
metrics: string[];
|
||||
window: { from: string; to: string };
|
||||
pairsTested: number;
|
||||
fdrQ: number;
|
||||
computedAt: string;
|
||||
}
|
||||
|
||||
/** UTC YYYY-MM-DD boundary key for a row, in the user's tz. */
|
||||
function dateKeyFor(now: Date, tz: string): string {
|
||||
const { year, month, day } = getLocalDateParts(now, tz);
|
||||
return `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
|
||||
}
|
||||
|
||||
// ── prompt ──────────────────────────────────────────────────────────────
|
||||
|
||||
const SYSTEM_PROMPT_EN = `You summarise one person's health-tracking PERIOD (a week or a month) for that person.
|
||||
Prompt version: ${NARRATIVE_PROMPT_VERSION}.
|
||||
|
||||
Hard rules:
|
||||
- The supplied CONTEXT is the ONLY source of truth. Never state a number, trend, driver, or threshold that is not in it.
|
||||
- Be DESCRIPTIVE, never CAUSAL. Say "X moved with Y" or "X was associated with Y", never "X caused Y" or "because of X".
|
||||
- The listed drivers already survived statistical multiple-comparison control; restate them only as associations and keep their conservative meaning.
|
||||
- No diagnosis, no medical advice, no alarm. Calm, factual, second person ("your").
|
||||
- 2 to 4 short sentences. Plain text only — no markdown, no headings, no bullet points, no emojis.
|
||||
- If the context is thin, say plainly that there is little to report this period rather than inventing detail.`;
|
||||
|
||||
const SYSTEM_PROMPT_DE = `Du fasst den Gesundheits-Tracking-ZEITRAUM einer Person (eine Woche oder einen Monat) für diese Person zusammen.
|
||||
Prompt-Version: ${NARRATIVE_PROMPT_VERSION}.
|
||||
|
||||
Feste Regeln:
|
||||
- Der bereitgestellte KONTEXT ist die EINZIGE Wahrheitsquelle. Nenne nie eine Zahl, einen Trend, einen Zusammenhang oder einen Schwellenwert, der nicht darin steht.
|
||||
- Sei BESCHREIBEND, nie URSÄCHLICH. Sage "X bewegte sich mit Y" oder "X war mit Y assoziiert", nie "X verursachte Y" oder "wegen X".
|
||||
- Die genannten Zusammenhänge haben bereits die statistische Mehrfachvergleichskorrektur überstanden; gib sie nur als Assoziationen wieder und bewahre ihre vorsichtige Bedeutung.
|
||||
- Keine Diagnose, kein medizinischer Rat, keine Panik. Ruhig, sachlich, in der zweiten Person ("dein").
|
||||
- 2 bis 4 kurze Sätze. Nur Klartext — kein Markdown, keine Überschriften, keine Aufzählungen, keine Emojis.
|
||||
- Wenn der Kontext dünn ist, sage klar, dass es in diesem Zeitraum wenig zu berichten gibt, statt Details zu erfinden.`;
|
||||
|
||||
/** Render the typed context into a compact, model-readable block. */
|
||||
export function buildNarrativeUserPrompt(
|
||||
context: PeriodNarrativeContext,
|
||||
locale: "de" | "en",
|
||||
): string {
|
||||
const periodLabel =
|
||||
context.period === "week"
|
||||
? locale === "de"
|
||||
? "die letzte Woche (7 Tage)"
|
||||
: "the last week (7 days)"
|
||||
: locale === "de"
|
||||
? "den letzten Monat (30 Tage)"
|
||||
: "the last month (30 days)";
|
||||
|
||||
const lines: string[] = [];
|
||||
lines.push(
|
||||
locale === "de"
|
||||
? `Zeitraum: ${periodLabel}, verglichen mit dem vorherigen gleich langen Zeitraum.`
|
||||
: `Period: ${periodLabel}, compared with the prior period of equal length.`,
|
||||
);
|
||||
|
||||
if (context.metricDeltas.length > 0) {
|
||||
lines.push(locale === "de" ? "Veränderungen:" : "Changes:");
|
||||
for (const d of context.metricDeltas) {
|
||||
if (d.current === null) continue;
|
||||
const unit = d.unit ? ` ${d.unit}` : "";
|
||||
const deltaPart =
|
||||
d.delta === null
|
||||
? locale === "de"
|
||||
? "(kein Vergleich möglich)"
|
||||
: "(no comparison available)"
|
||||
: `${d.delta >= 0 ? "+" : ""}${d.delta}${unit}${
|
||||
d.deltaPercent === null ? "" : ` (${d.deltaPercent}%)`
|
||||
}`;
|
||||
lines.push(
|
||||
`- ${d.type}: ${d.current}${unit} ${deltaPart} [${d.currentDays}d]`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (context.bandTransitions.length > 0) {
|
||||
lines.push(
|
||||
locale === "de"
|
||||
? "Persönlicher Normbereich (Median ± Streuung des Vorzeitraums):"
|
||||
: "Personal typical range (prior-period median ± spread):",
|
||||
);
|
||||
for (const b of context.bandTransitions) {
|
||||
const where =
|
||||
b.direction === "above"
|
||||
? locale === "de"
|
||||
? "über dem Bereich"
|
||||
: "above the range"
|
||||
: b.direction === "below"
|
||||
? locale === "de"
|
||||
? "unter dem Bereich"
|
||||
: "below the range"
|
||||
: locale === "de"
|
||||
? "im Bereich"
|
||||
: "in range";
|
||||
lines.push(
|
||||
`- ${b.type}: ${b.center} (${b.bandLow}–${b.bandHigh}) → ${where}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (context.drivers.length > 0) {
|
||||
lines.push(
|
||||
locale === "de"
|
||||
? "Statistisch belegte Assoziationen (NICHT kausal):"
|
||||
: "Statistically supported associations (NOT causal):",
|
||||
);
|
||||
for (const dr of context.drivers) {
|
||||
lines.push(
|
||||
`- ${dr.behaviour} ~ ${dr.outcome}: r=${dr.r}, q=${dr.qValue}, n=${dr.n} — ${dr.interpretation}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (context.coincidentFlags.length > 0) {
|
||||
lines.push(
|
||||
locale === "de"
|
||||
? `Tage mit mehreren gleichzeitig außerhalb des Normbereichs liegenden Werten: ${context.coincidentFlags.length}.`
|
||||
: `Days with several vitals outside the typical range together: ${context.coincidentFlags.length}.`,
|
||||
);
|
||||
}
|
||||
|
||||
lines.push(
|
||||
locale === "de"
|
||||
? `(${context.pairsTested} Paare getestet, FDR-Ziel q=${context.fdrQ}.)`
|
||||
: `(${context.pairsTested} pairs tested, FDR target q=${context.fdrQ}.)`,
|
||||
);
|
||||
|
||||
return lines.join("\n");
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate + cache the period narrative for one user. Pure pipeline; no
|
||||
* rate-limit / request concerns (the route + cron add those). Returns a typed
|
||||
* outcome the caller can log + branch on. Never throws on a provider failure
|
||||
* (a cron batch loop must continue to the next user).
|
||||
*/
|
||||
export async function generatePeriodNarrative(
|
||||
userId: string,
|
||||
options: GenerateOptions,
|
||||
): Promise<NarrativeGenerateOutcome> {
|
||||
const { locale } = options;
|
||||
const force = options.force === true;
|
||||
const now = options.now ?? new Date();
|
||||
const prisma = options.prisma ?? defaultPrisma;
|
||||
const buildContext = options.buildContext ?? buildPeriodNarrativeContext;
|
||||
const runCompletion = options.runCompletion ?? runStatusCompletion;
|
||||
const period = options.period;
|
||||
|
||||
// Freshness short-circuit — a recently-generated row is served as-is.
|
||||
if (!force) {
|
||||
const existing = await prisma.insightNarrative.findUnique({
|
||||
where: { userId_period_locale: { userId, period, locale } },
|
||||
select: { updatedAt: true },
|
||||
});
|
||||
if (
|
||||
existing &&
|
||||
now.getTime() - existing.updatedAt.getTime() < NARRATIVE_FRESH_MS
|
||||
) {
|
||||
return { status: "cached" };
|
||||
}
|
||||
}
|
||||
|
||||
const context = await buildContext(userId, { period, now });
|
||||
if (context.status === "insufficient") {
|
||||
annotate({
|
||||
action: { name: "insights.narrative.insufficient" },
|
||||
meta: { period, reason: context.reason },
|
||||
});
|
||||
return { status: "insufficient" };
|
||||
}
|
||||
|
||||
const profile = await prisma.user.findUnique({
|
||||
where: { id: userId },
|
||||
select: { timezone: true },
|
||||
});
|
||||
const tz = profile?.timezone ?? "Europe/Berlin";
|
||||
|
||||
const completion = await runCompletion({
|
||||
userId,
|
||||
cacheAction: `insights.narrative.${period}.${locale}`,
|
||||
systemPrompt: locale === "de" ? SYSTEM_PROMPT_DE : SYSTEM_PROMPT_EN,
|
||||
userPrompt: buildNarrativeUserPrompt(context, locale),
|
||||
temperature: 0.3,
|
||||
maxTokens: 400,
|
||||
});
|
||||
|
||||
if (completion.kind === "none") {
|
||||
return { status: "skipped", reason: "no-provider" };
|
||||
}
|
||||
if (completion.kind === "timeout") {
|
||||
annotate({
|
||||
action: { name: "insights.narrative.timeout" },
|
||||
meta: { period, locale },
|
||||
});
|
||||
return { status: "failed", reason: "timeout" };
|
||||
}
|
||||
if (completion.kind === "error") {
|
||||
return { status: "failed", reason: "provider-error" };
|
||||
}
|
||||
|
||||
const text = completion.content.trim();
|
||||
if (text.length === 0) {
|
||||
return { status: "failed", reason: "empty" };
|
||||
}
|
||||
|
||||
const provenance: NarrativeProvenancePayload = {
|
||||
metrics: context.provenance.metrics,
|
||||
window: context.provenance.window,
|
||||
pairsTested: context.pairsTested,
|
||||
fdrQ: context.fdrQ,
|
||||
computedAt: context.provenance.computedAt,
|
||||
};
|
||||
|
||||
// Upsert the single (user, period, locale) row in place — delete/regenerate
|
||||
// clean by construction. The prose is held AES-256-GCM at rest.
|
||||
const encryptedContent = encryptToBytes(text);
|
||||
const dateKey = dateKeyFor(now, tz);
|
||||
await prisma.insightNarrative.upsert({
|
||||
where: { userId_period_locale: { userId, period, locale } },
|
||||
create: {
|
||||
userId,
|
||||
period,
|
||||
locale,
|
||||
dateKey,
|
||||
encryptedContent,
|
||||
provenanceJson: JSON.stringify(provenance),
|
||||
providerType: completion.providerType,
|
||||
promptVersion: NARRATIVE_PROMPT_VERSION,
|
||||
},
|
||||
update: {
|
||||
dateKey,
|
||||
encryptedContent,
|
||||
provenanceJson: JSON.stringify(provenance),
|
||||
providerType: completion.providerType,
|
||||
promptVersion: NARRATIVE_PROMPT_VERSION,
|
||||
},
|
||||
});
|
||||
|
||||
annotate({
|
||||
action: { name: "insights.narrative.generated" },
|
||||
meta: { period, locale, provider: completion.providerType },
|
||||
});
|
||||
return { status: "generated", providerType: completion.providerType };
|
||||
}
|
||||
|
||||
/** The narrative row, decrypted for a read. */
|
||||
export interface NarrativeRead {
|
||||
period: NarrativePeriod;
|
||||
locale: "de" | "en";
|
||||
text: string;
|
||||
dateKey: string;
|
||||
provenance: NarrativeProvenancePayload | null;
|
||||
providerType: string | null;
|
||||
promptVersion: string | null;
|
||||
updatedAt: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the latest narrative for `(userId, period, locale)`, decrypting the
|
||||
* prose. Null when none was ever generated. This is the stale-while-revalidate
|
||||
* source: it returns whatever was last produced, regardless of age, so the
|
||||
* surface renders prior prose immediately while a refresh warms out of band.
|
||||
*/
|
||||
export async function readPeriodNarrative(
|
||||
userId: string,
|
||||
period: NarrativePeriod,
|
||||
locale: "de" | "en",
|
||||
prisma: PrismaClient = defaultPrisma,
|
||||
): Promise<NarrativeRead | null> {
|
||||
const row = await prisma.insightNarrative.findUnique({
|
||||
where: { userId_period_locale: { userId, period, locale } },
|
||||
});
|
||||
if (!row) return null;
|
||||
|
||||
let text: string;
|
||||
try {
|
||||
text = decryptFromBytes(row.encryptedContent);
|
||||
} catch {
|
||||
// A row we cannot decrypt is treated as absent — the caller regenerates.
|
||||
return null;
|
||||
}
|
||||
|
||||
let provenance: NarrativeProvenancePayload | null = null;
|
||||
if (row.provenanceJson) {
|
||||
try {
|
||||
provenance = JSON.parse(row.provenanceJson) as NarrativeProvenancePayload;
|
||||
} catch {
|
||||
provenance = null;
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
period: row.period as NarrativePeriod,
|
||||
locale: row.locale as "de" | "en",
|
||||
text,
|
||||
dateKey: row.dateKey,
|
||||
provenance,
|
||||
providerType: row.providerType,
|
||||
promptVersion: row.promptVersion,
|
||||
updatedAt: row.updatedAt.toISOString(),
|
||||
};
|
||||
}
|
||||
|
||||
// ── helpers ───────────────────────────────────────────────────────────────
|
||||
|
||||
/** Prisma `Bytes` ↔ ciphertext, mirroring the CoachMessage helper. */
|
||||
function encryptToBytes(plaintext: string): Uint8Array<ArrayBuffer> {
|
||||
const ciphertext = encrypt(plaintext);
|
||||
const encoded = Buffer.from(ciphertext, "utf8");
|
||||
const out = new Uint8Array(new ArrayBuffer(encoded.byteLength));
|
||||
out.set(encoded);
|
||||
return out;
|
||||
}
|
||||
|
||||
function decryptFromBytes(buf: Uint8Array): string {
|
||||
return decrypt(Buffer.from(buf).toString("utf8"));
|
||||
}
|
||||
@@ -0,0 +1,167 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
|
||||
const checkRateLimit = vi.fn();
|
||||
const getAssistantFlags = vi.fn();
|
||||
|
||||
vi.mock("@/lib/rate-limit", () => ({
|
||||
checkRateLimit: (...a: unknown[]) => checkRateLimit(...a),
|
||||
}));
|
||||
vi.mock("@/lib/feature-flags", () => ({
|
||||
getAssistantFlags: (...a: unknown[]) => getAssistantFlags(...a),
|
||||
}));
|
||||
// Never reach the real generator (which imports the provider chain).
|
||||
vi.mock("@/lib/insights/narrative/period-narrative-generate", () => ({
|
||||
generatePeriodNarrative: vi.fn(),
|
||||
}));
|
||||
vi.mock("@/lib/logging/context", () => ({ annotate: vi.fn() }));
|
||||
|
||||
import {
|
||||
runPeriodNarrativeWarm,
|
||||
periodsForDay,
|
||||
findNarrativeCandidates,
|
||||
PERIOD_NARRATIVE_QUEUE,
|
||||
PERIOD_NARRATIVE_CRON,
|
||||
} from "../period-narrative-warm";
|
||||
|
||||
function makePrisma(users: Array<{ id: string; locale: string | null }>) {
|
||||
const findMany = vi.fn().mockResolvedValue(users);
|
||||
return { prisma: { user: { findMany } }, findMany };
|
||||
}
|
||||
|
||||
// A Monday that is also the 1st of the month — both periods warm.
|
||||
const MON_FIRST = new Date("2026-06-01T03:05:00.000Z");
|
||||
// A plain Tuesday mid-month — no boundary.
|
||||
const TUE_MID = new Date("2026-06-02T03:05:00.000Z");
|
||||
// A Monday that is not the 1st — week only.
|
||||
const MON_MID = new Date("2026-06-08T03:05:00.000Z");
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
getAssistantFlags.mockResolvedValue({
|
||||
enabled: true,
|
||||
briefing: true,
|
||||
insightStatus: true,
|
||||
});
|
||||
checkRateLimit.mockResolvedValue({ allowed: true });
|
||||
});
|
||||
|
||||
describe("periodsForDay — boundary gate", () => {
|
||||
it("warms week on a Monday", () => {
|
||||
expect(periodsForDay(MON_MID)).toContain("week");
|
||||
expect(periodsForDay(MON_MID)).not.toContain("month");
|
||||
});
|
||||
it("warms month on the 1st", () => {
|
||||
expect(periodsForDay(MON_FIRST)).toContain("month");
|
||||
});
|
||||
it("warms nothing on a plain mid-week day", () => {
|
||||
expect(periodsForDay(TUE_MID)).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("findNarrativeCandidates", () => {
|
||||
it("filters coach-enabled users, capped", async () => {
|
||||
const { prisma, findMany } = makePrisma([{ id: "u1", locale: "de" }]);
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
await findNarrativeCandidates(prisma as any, 50);
|
||||
const arg = findMany.mock.calls[0][0];
|
||||
expect(arg.where.disableCoach).toBe(false);
|
||||
expect(arg.take).toBe(50);
|
||||
});
|
||||
});
|
||||
|
||||
describe("runPeriodNarrativeWarm", () => {
|
||||
it("is a no-op on a non-boundary night (no generation)", async () => {
|
||||
const { prisma, findMany } = makePrisma([{ id: "u1", locale: "de" }]);
|
||||
const generate = vi.fn();
|
||||
const result = await runPeriodNarrativeWarm(
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
prisma as any,
|
||||
{ now: TUE_MID, generate },
|
||||
);
|
||||
expect(result.periods).toEqual([]);
|
||||
expect(findMany).not.toHaveBeenCalled();
|
||||
expect(generate).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("generates the boundary periods for each candidate, gated by budget", async () => {
|
||||
const { prisma } = makePrisma([
|
||||
{ id: "u1", locale: "de" },
|
||||
{ id: "u2", locale: "en" },
|
||||
]);
|
||||
const generate = vi
|
||||
.fn()
|
||||
.mockResolvedValue({ status: "generated", providerType: "openai" });
|
||||
const result = await runPeriodNarrativeWarm(
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
prisma as any,
|
||||
{ now: MON_FIRST, generate },
|
||||
);
|
||||
expect(result.periods.sort()).toEqual(["month", "week"]);
|
||||
// 2 users × 2 periods.
|
||||
expect(generate).toHaveBeenCalledTimes(4);
|
||||
expect(result.generated).toBe(4);
|
||||
// Budget bucket checked once per user.
|
||||
expect(checkRateLimit).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it("skips a budget-blocked user without generating", async () => {
|
||||
const { prisma } = makePrisma([{ id: "u1", locale: "de" }]);
|
||||
checkRateLimit.mockResolvedValueOnce({ allowed: false });
|
||||
const generate = vi.fn();
|
||||
const result = await runPeriodNarrativeWarm(
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
prisma as any,
|
||||
{ now: MON_MID, generate },
|
||||
);
|
||||
expect(result.budgetBlocked).toBe(1);
|
||||
expect(generate).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("short-circuits when the briefing surface is disabled", async () => {
|
||||
getAssistantFlags.mockResolvedValueOnce({
|
||||
enabled: false,
|
||||
briefing: false,
|
||||
insightStatus: false,
|
||||
});
|
||||
const { prisma, findMany } = makePrisma([{ id: "u1", locale: "de" }]);
|
||||
const generate = vi.fn();
|
||||
const result = await runPeriodNarrativeWarm(
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
prisma as any,
|
||||
{ now: MON_FIRST, generate },
|
||||
);
|
||||
expect(result.periods).toEqual([]);
|
||||
expect(findMany).not.toHaveBeenCalled();
|
||||
expect(generate).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe("queue registration", () => {
|
||||
const workerSrc = fs.readFileSync(
|
||||
path.resolve(__dirname, "../reminder-worker.ts"),
|
||||
"utf8",
|
||||
);
|
||||
|
||||
it("registers the queue in the allQueues createQueue loop", () => {
|
||||
const match = workerSrc.match(/const allQueues\s*=\s*\[([\s\S]*?)\];/);
|
||||
expect(match).not.toBeNull();
|
||||
expect(match![1]).toMatch(/\bPERIOD_NARRATIVE_QUEUE\b/);
|
||||
});
|
||||
|
||||
it("schedules the cron in the schedules table", () => {
|
||||
expect(workerSrc).toMatch(
|
||||
/\[\s*PERIOD_NARRATIVE_QUEUE\s*,\s*PERIOD_NARRATIVE_CRON\s*\]/,
|
||||
);
|
||||
});
|
||||
|
||||
it("registers a boss.work handler for the queue", () => {
|
||||
expect(workerSrc).toMatch(/boss\.work[\s\S]{0,120}PERIOD_NARRATIVE_QUEUE/);
|
||||
});
|
||||
|
||||
it("exposes a sane queue name + nightly cron", () => {
|
||||
expect(PERIOD_NARRATIVE_QUEUE).toBe("period-narrative-warm");
|
||||
expect(PERIOD_NARRATIVE_CRON).toMatch(/^\d+\s+\d+\s+\*\s+\*\s+\*$/);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,75 @@
|
||||
/**
|
||||
* v1.11.0 W3 — generator-free contract for the period-narrative warm queue.
|
||||
*
|
||||
* The read-only GET route enqueues a single-user warm here without importing
|
||||
* the concrete generator (which would pull the provider chain + W2 context
|
||||
* assembler into the route bundle). The worker-only pipeline
|
||||
* (`runPeriodNarrativeWarm`) lives in `period-narrative-warm.ts`, which
|
||||
* re-exports the queue name from here so there is one source of truth.
|
||||
*
|
||||
* Mirrors the `insight-pregenerate-shared.ts` split exactly: queue name +
|
||||
* payload type + cron + enqueue helper here, the concrete dispatch in the
|
||||
* worker module.
|
||||
*/
|
||||
import { getGlobalBoss } from "@/lib/jobs/boss-instance";
|
||||
import { annotate } from "@/lib/logging/context";
|
||||
import type { NarrativePeriod } from "@/lib/insights/narrative/period-narrative";
|
||||
|
||||
export const PERIOD_NARRATIVE_QUEUE = "period-narrative-warm";
|
||||
|
||||
/**
|
||||
* Nightly at 05:05 Europe/Berlin — inside the existing maintenance window,
|
||||
* after the comprehensive insight pre-generation (04:30) and the computed
|
||||
* scores (04:45–04:55) so the rollup signals it reads are already folded.
|
||||
* The handler only does real work near a week/month boundary; on every other
|
||||
* night it short-circuits cheaply.
|
||||
*/
|
||||
export const PERIOD_NARRATIVE_CRON = "5 5 * * *";
|
||||
|
||||
export interface PeriodNarrativePayload {
|
||||
/** Set on the nightly scheduled tick (informational). */
|
||||
triggeredAt?: string;
|
||||
/** Single-user warm enqueued by the read-only GET on a cold/stale read. */
|
||||
userId?: string;
|
||||
/** Period to warm on the single-user path. */
|
||||
period?: NarrativePeriod;
|
||||
/** Locale to warm; defaults to "de" when absent. */
|
||||
locale?: "de" | "en";
|
||||
}
|
||||
|
||||
/**
|
||||
* Fire-and-forget enqueue used by the read-only GET on a cold/stale read. A
|
||||
* `singletonKey` per `(user, period, locale)` collapses repeated reads within
|
||||
* a short window into one queued job. No-ops cleanly when the global boss is
|
||||
* unavailable (a web process without an embedded worker) — the nightly cron
|
||||
* remains the catch-net.
|
||||
*/
|
||||
export async function enqueueNarrativeWarm(payload: {
|
||||
userId: string;
|
||||
period: NarrativePeriod;
|
||||
locale: "de" | "en";
|
||||
}): Promise<void> {
|
||||
const boss = getGlobalBoss();
|
||||
if (!boss) return;
|
||||
try {
|
||||
await boss.send(
|
||||
PERIOD_NARRATIVE_QUEUE,
|
||||
{
|
||||
userId: payload.userId,
|
||||
period: payload.period,
|
||||
locale: payload.locale,
|
||||
} satisfies PeriodNarrativePayload,
|
||||
{
|
||||
singletonKey: `warm:${payload.userId}:${payload.period}:${payload.locale}`,
|
||||
singletonSeconds: 120,
|
||||
},
|
||||
);
|
||||
annotate({
|
||||
action: { name: "insights.narrative.warm.enqueued" },
|
||||
meta: { period: payload.period, locale: payload.locale },
|
||||
});
|
||||
} catch {
|
||||
// Best-effort — a failure just means the narrative stays as-is until the
|
||||
// next read or the nightly cron warms it.
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,236 @@
|
||||
/**
|
||||
* v1.11.0 W3 — nightly period-narrative warm cron + single-user dispatch.
|
||||
*
|
||||
* The nightly tick warms the latest week/month narrative for data-bearing,
|
||||
* coach-enabled users so the Insights overview renders the summary instantly
|
||||
* the morning after a period boundary, never blocking the first mount on the
|
||||
* provider. The handler only fans out near a boundary:
|
||||
* - the WEEK narrative warms on Mondays (the day after a week closes),
|
||||
* - the MONTH narrative warms on the 1st of the month.
|
||||
* On every other night it short-circuits to a no-op for cheapness.
|
||||
*
|
||||
* Budget gate (mirrors `insight-pregenerate`): a per-user rate-limit bucket
|
||||
* (`period-narrative:<userId>`, one warm / 20 h) bounds nightly LLM cost, and
|
||||
* a per-run batch cap bounds a single tick. The generator no-ops cleanly
|
||||
* without a provider (one cheap chain-resolve, no LLM) and writes nothing on
|
||||
* an insufficient context, so a provider-less / sparse account is near-free.
|
||||
*
|
||||
* Recurring pg-boss task — never runs inside an HTTP request, never shells out
|
||||
* to `tsx` (CLAUDE.md DO-NOTs).
|
||||
*/
|
||||
import type { PrismaClient } from "@/generated/prisma/client";
|
||||
import { checkRateLimit } from "@/lib/rate-limit";
|
||||
import { getAssistantFlags } from "@/lib/feature-flags";
|
||||
import { annotate } from "@/lib/logging/context";
|
||||
import {
|
||||
generatePeriodNarrative,
|
||||
type NarrativeGenerateOutcome,
|
||||
} from "@/lib/insights/narrative/period-narrative-generate";
|
||||
import type { NarrativePeriod } from "@/lib/insights/narrative/period-narrative";
|
||||
import {
|
||||
PERIOD_NARRATIVE_QUEUE,
|
||||
PERIOD_NARRATIVE_CRON,
|
||||
enqueueNarrativeWarm,
|
||||
type PeriodNarrativePayload,
|
||||
} from "@/lib/jobs/period-narrative-shared";
|
||||
|
||||
export {
|
||||
PERIOD_NARRATIVE_QUEUE,
|
||||
PERIOD_NARRATIVE_CRON,
|
||||
enqueueNarrativeWarm,
|
||||
};
|
||||
export type { PeriodNarrativePayload };
|
||||
|
||||
/** Per-run cap on the number of users a single tick generates for. */
|
||||
export const NARRATIVE_BATCH_CAP = 200;
|
||||
|
||||
/** Per-user budget bucket window — one warm per 20 h. */
|
||||
const NARRATIVE_BUDGET_WINDOW_MS = 20 * 60 * 60 * 1000;
|
||||
|
||||
export interface NarrativeWarmRunResult {
|
||||
/** Periods warmed this tick (empty when not on a boundary night). */
|
||||
periods: NarrativePeriod[];
|
||||
total: number;
|
||||
generated: number;
|
||||
cached: number;
|
||||
skipped: number;
|
||||
insufficient: number;
|
||||
failed: number;
|
||||
budgetBlocked: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Which period narratives a given calendar day should warm. The week
|
||||
* narrative warms on Mondays (`getDay() === 1`); the month narrative warms on
|
||||
* the 1st. A day can be both (the 1st falling on a Monday). Returns an empty
|
||||
* list on a non-boundary day, so the nightly cron is a no-op most nights.
|
||||
*
|
||||
* Exported + pure so the cron test can pin the boundary logic without a clock.
|
||||
*/
|
||||
export function periodsForDay(now: Date, tz = "Europe/Berlin"): NarrativePeriod[] {
|
||||
// Resolve the local weekday + day-of-month in the maintenance-window tz so
|
||||
// the boundary matches the user-facing calendar, not UTC.
|
||||
const parts = new Intl.DateTimeFormat("en-US", {
|
||||
timeZone: tz,
|
||||
weekday: "short",
|
||||
day: "numeric",
|
||||
}).formatToParts(now);
|
||||
const weekday = parts.find((p) => p.type === "weekday")?.value;
|
||||
const dayOfMonth = Number(parts.find((p) => p.type === "day")?.value);
|
||||
|
||||
const periods: NarrativePeriod[] = [];
|
||||
if (weekday === "Mon") periods.push("week");
|
||||
if (dayOfMonth === 1) periods.push("month");
|
||||
return periods;
|
||||
}
|
||||
|
||||
interface NarrativeCandidate {
|
||||
id: string;
|
||||
locale: string | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Discovery query — coach-enabled users, oldest-narrative-first so the
|
||||
* staleest users are served before the per-run cap bites. Whether a user has
|
||||
* a provider / enough history is confirmed inside the generator (skipped /
|
||||
* insufficient), so a provider-less or sparse account costs at most one cheap
|
||||
* chain-resolve and no LLM call.
|
||||
*/
|
||||
export async function findNarrativeCandidates(
|
||||
prisma: PrismaClient,
|
||||
cap: number,
|
||||
): Promise<NarrativeCandidate[]> {
|
||||
return prisma.user.findMany({
|
||||
where: { disableCoach: false },
|
||||
take: cap,
|
||||
select: { id: true, locale: true },
|
||||
});
|
||||
}
|
||||
|
||||
function normalizeLocale(value: string | null): "de" | "en" {
|
||||
return value === "en" ? "en" : "de";
|
||||
}
|
||||
|
||||
/**
|
||||
* Run one nightly warm pass. Pure of pg-boss so the unit test can drive it
|
||||
* directly. Short-circuits to a no-op when (a) the master assistant briefing
|
||||
* switch is off or (b) the night is not a period boundary. The per-user
|
||||
* budget gate runs BEFORE the LLM call so a no-op night costs only
|
||||
* rate-limit upserts.
|
||||
*/
|
||||
export async function runPeriodNarrativeWarm(
|
||||
prisma: PrismaClient,
|
||||
options: {
|
||||
now?: Date;
|
||||
cap?: number;
|
||||
/** Injected for the test — defaults to the real generator. */
|
||||
generate?: typeof generatePeriodNarrative;
|
||||
} = {},
|
||||
): Promise<NarrativeWarmRunResult> {
|
||||
const now = options.now ?? new Date();
|
||||
const cap = options.cap ?? NARRATIVE_BATCH_CAP;
|
||||
const generate = options.generate ?? generatePeriodNarrative;
|
||||
|
||||
const result: NarrativeWarmRunResult = {
|
||||
periods: [],
|
||||
total: 0,
|
||||
generated: 0,
|
||||
cached: 0,
|
||||
skipped: 0,
|
||||
insufficient: 0,
|
||||
failed: 0,
|
||||
budgetBlocked: 0,
|
||||
};
|
||||
|
||||
const flags = await getAssistantFlags();
|
||||
if (!flags.briefing) return result;
|
||||
|
||||
const periods = periodsForDay(now);
|
||||
result.periods = periods;
|
||||
if (periods.length === 0) return result;
|
||||
|
||||
const candidates = await findNarrativeCandidates(prisma, cap);
|
||||
result.total = candidates.length;
|
||||
|
||||
for (const candidate of candidates) {
|
||||
const budget = await checkRateLimit(
|
||||
`period-narrative:${candidate.id}`,
|
||||
1,
|
||||
NARRATIVE_BUDGET_WINDOW_MS,
|
||||
);
|
||||
if (!budget.allowed) {
|
||||
result.budgetBlocked++;
|
||||
continue;
|
||||
}
|
||||
|
||||
const locale = normalizeLocale(candidate.locale);
|
||||
for (const period of periods) {
|
||||
const outcome = await generate(candidate.id, {
|
||||
period,
|
||||
locale,
|
||||
force: true,
|
||||
now,
|
||||
});
|
||||
tally(result, outcome);
|
||||
}
|
||||
}
|
||||
|
||||
annotate({
|
||||
action: { name: "insights.narrative.warm.run" },
|
||||
meta: {
|
||||
periods,
|
||||
total: result.total,
|
||||
generated: result.generated,
|
||||
cached: result.cached,
|
||||
skipped: result.skipped,
|
||||
insufficient: result.insufficient,
|
||||
failed: result.failed,
|
||||
budget_blocked: result.budgetBlocked,
|
||||
},
|
||||
});
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
function tally(
|
||||
result: NarrativeWarmRunResult,
|
||||
outcome: NarrativeGenerateOutcome,
|
||||
): void {
|
||||
switch (outcome.status) {
|
||||
case "generated":
|
||||
result.generated++;
|
||||
break;
|
||||
case "cached":
|
||||
result.cached++;
|
||||
break;
|
||||
case "skipped":
|
||||
result.skipped++;
|
||||
break;
|
||||
case "insufficient":
|
||||
result.insufficient++;
|
||||
break;
|
||||
case "failed":
|
||||
result.failed++;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Single-user warm enqueued by the read-only GET on a cold/stale read. Runs
|
||||
* the generator directly for one (user, period, locale) WITHOUT the nightly
|
||||
* budget bucket (the enqueue's `singletonKey` is the anti-spam layer). The
|
||||
* generator no-ops cleanly without a provider and writes nothing on an
|
||||
* insufficient context, so this is bounded by construction.
|
||||
*/
|
||||
export async function warmOneNarrative(
|
||||
payload: PeriodNarrativePayload,
|
||||
): Promise<NarrativeGenerateOutcome | null> {
|
||||
if (!payload.userId || !payload.period) return null;
|
||||
const flags = await getAssistantFlags();
|
||||
if (!flags.briefing && !flags.insightStatus) return null;
|
||||
return generatePeriodNarrative(payload.userId, {
|
||||
period: payload.period,
|
||||
locale: payload.locale ?? "de",
|
||||
force: true,
|
||||
});
|
||||
}
|
||||
@@ -95,6 +95,13 @@ import {
|
||||
STRAIN_SCORE_CRON,
|
||||
runStrainScore,
|
||||
} from "@/lib/jobs/strain-score";
|
||||
import {
|
||||
PERIOD_NARRATIVE_QUEUE,
|
||||
PERIOD_NARRATIVE_CRON,
|
||||
runPeriodNarrativeWarm,
|
||||
warmOneNarrative,
|
||||
type PeriodNarrativePayload,
|
||||
} from "@/lib/jobs/period-narrative-warm";
|
||||
import {
|
||||
DENSE_INTRADAY_RETENTION_QUEUE,
|
||||
DENSE_INTRADAY_RETENTION_CONCURRENCY,
|
||||
@@ -2318,6 +2325,10 @@ export async function startReminderWorker() {
|
||||
// onto the drain-cumulative tick). The queue MUST be registered here or
|
||||
// the boot enqueue silently never drains.
|
||||
DENSE_INTRADAY_RETENTION_QUEUE,
|
||||
// v1.11.0 — nightly period-narrative warm + single-user warm enqueued by
|
||||
// the read-only narrative GET. The queue MUST be registered here or the
|
||||
// GET-miss enqueue silently never warms.
|
||||
PERIOD_NARRATIVE_QUEUE,
|
||||
];
|
||||
|
||||
for (const q of allQueues) {
|
||||
@@ -2429,6 +2440,10 @@ export async function startReminderWorker() {
|
||||
// Strain-score compute + store, after the recovery + stress passes so
|
||||
// the nightly score writes stay ordered.
|
||||
[STRAIN_SCORE_QUEUE, STRAIN_SCORE_CRON],
|
||||
// v1.11.0 — nightly 05:05 Europe/Berlin period-narrative warm. The
|
||||
// handler only fans out on a week (Mon) / month (1st) boundary; every
|
||||
// other night is a cheap no-op. Budget-gated per user inside the runner.
|
||||
[PERIOD_NARRATIVE_QUEUE, PERIOD_NARRATIVE_CRON],
|
||||
];
|
||||
|
||||
for (const [name, cron] of schedules) {
|
||||
@@ -2694,6 +2709,34 @@ export async function startReminderWorker() {
|
||||
}
|
||||
},
|
||||
);
|
||||
// v1.11.0 — period-narrative warm. A scheduled tick (no `userId`) runs the
|
||||
// boundary-gated nightly fan-out; a `userId` payload runs a single-user warm
|
||||
// enqueued by the read-only GET on a cold/stale read. Single-flight so two
|
||||
// ticks never double-walk the cohort; the per-user budget gate covers the
|
||||
// fan-out and the enqueue `singletonKey` covers the single-user path.
|
||||
await boss.work<PeriodNarrativePayload>(
|
||||
PERIOD_NARRATIVE_QUEUE,
|
||||
{ localConcurrency: 1 },
|
||||
async (jobs) => {
|
||||
for (const job of jobs) {
|
||||
try {
|
||||
if (job.data?.userId) {
|
||||
await warmOneNarrative(job.data);
|
||||
} else {
|
||||
const summary = await runPeriodNarrativeWarm(getWorkerPrisma());
|
||||
workerLog(
|
||||
"info",
|
||||
`[period-narrative] periods=${summary.periods.join(",") || "none"} total=${summary.total} generated=${summary.generated} cached=${summary.cached} skipped=${summary.skipped} insufficient=${summary.insufficient} failed=${summary.failed} budget=${summary.budgetBlocked}`,
|
||||
);
|
||||
}
|
||||
} catch (err) {
|
||||
recordError();
|
||||
workerLog("error", "[period-narrative] warm failed", err);
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
},
|
||||
);
|
||||
// v1.8.3 — on-demand per-metric status generation enqueued by the
|
||||
// read-only status route on a cold card. Low concurrency so a first
|
||||
// visit that cold-misses several cards can't saturate the Prisma pool
|
||||
|
||||
@@ -101,6 +101,13 @@ export const queryKeys = {
|
||||
* without a second LLM round-trip.
|
||||
*/
|
||||
insightsAdvisor: () => ["insights", "advisor"] as const,
|
||||
/**
|
||||
* v1.11.0 — period-narrative summary (`/api/insights/narrative?period=…`).
|
||||
* Keyed by period + locale so the week and month summaries cache
|
||||
* independently and a locale switch fetches the matching prose.
|
||||
*/
|
||||
insightsNarrative: (period: string, locale: string) =>
|
||||
["insights", "narrative", period, locale] as const,
|
||||
insightsBpStatus: (locale: string) =>
|
||||
["insights", "blood-pressure-status", locale] as const,
|
||||
insightsWeightStatus: (locale: string) =>
|
||||
|
||||
Reference in new issue
Block a user