HealthLog/src/lib/insights/assessment-context.ts

/**
 * v1.12.1 — assessment-context helpers for the per-metric Insights cards.
 *
 * The per-metric assessment prompt is tightly grounded but its *form* used
 * to converge: every card opened the same way, forced the same "one doable
 * step", and a metric that stayed steady for weeks produced near-identical
 * paragraphs. None of that is a grounding or safety problem — it is a
 * diversity / repetition problem, fixable with signals already computed
 * server-side. This module turns those signals into small, locale-aware
 * prompt blocks the generator interpolates:
 *
 *   - a deterministic per-render VARIETY token (lead-with-trend vs
 *     lead-with-latest vs lead-with-consistency) so consecutive cards and
 *     consecutive days don't read the same. Seeded from
 *     `userId + metricId + dayKey` (NOT Math.random / Date.now — those are
 *     unavailable on this codebase's deterministic paths) so it is stable
 *     per render and unit-testable.
 *   - an explicit DATA STRENGTH line (n + recency) so the prose hedges on
 *     thin data instead of the model guessing what "few" means.
 *   - a REPETITION line ("you've reported 'steady' N times running") so the
 *     model varies or escalates instead of restating the same level.
 *   - a RELATIONS block carrying the FDR-surviving cross-metric correlations
 *     that involve THIS metric — already computed by the discovery engine,
 *     previously only surfaced in the period narrative.
 *
 * Everything here is PURE: callers fetch the data, this module formats it.
 * No grounding floor is touched — these blocks add context, they never relax
 * the own-baseline rule, the computed-stats rule, or the filler-phrase ban.
 */
import type { Locale } from "@/lib/i18n/config";

/**
 * Three rhetorical entry points the card can lead with. The grounding is
 * identical in every case — only the opening *angle* rotates, so a user
 * paging through ten metric cards doesn't read ten identically-shaped
 * paragraphs.
 */
export type VarietyLead = "trend" | "latest" | "consistency";

const VARIETY_LEADS: readonly VarietyLead[] = [
  "trend",
  "latest",
  "consistency",
] as const;

/**
 * Deterministic 32-bit FNV-1a hash. Stable across processes (no salt, no
 * platform dependence), so the same `(userId, metricId, dayKey)` always
 * picks the same lead — which makes the variety token reproducible and
 * directly unit-testable, and keeps a render idempotent within a day.
 */
function fnv1a(input: string): number {
  let hash = 0x811c9dc5;
  for (let i = 0; i < input.length; i++) {
    hash ^= input.charCodeAt(i);
    // Multiply by the FNV prime (0x01000193) in 32-bit space.
    hash = Math.imul(hash, 0x01000193);
  }
  // Coerce to an unsigned 32-bit integer.
  return hash >>> 0;
}

/**
 * Pick the per-render variety lead for this user × metric × day. Stable
 * (seeded, not random) so the same card re-renders identically within a
 * day, but rotates across metrics and across days.
 */
export function pickVarietyLead(
  userId: string,
  metricId: string,
  dayKey: string,
): VarietyLead {
  const seed = fnv1a(`${userId}|${metricId}|${dayKey}`);
  return VARIETY_LEADS[seed % VARIETY_LEADS.length];
}

/**
 * One short locale-aware hint nudging the opening angle. Kept advisory
 * ("you may open with …") so it never overrides the grounding rules when
 * the data makes a different lead the honest one.
 */
export function formatVarietyHint(lead: VarietyLead, locale: Locale): string {
  if (locale === "en") {
    const angle =
      lead === "trend"
        ? "the recent direction of travel (rising / falling / flat vs the baseline)"
        : lead === "latest"
          ? "the single most recent value and where it sits"
          : "how consistent or variable the readings have been";
    return `VARIETY: to keep your cards from reading the same, you may open this one by leading with ${angle} — only if the data genuinely supports that angle; never force it, never invent a trend.`;
  }
  const angle =
    lead === "trend"
      ? "der jüngsten Richtung (steigend / fallend / flach gegenüber der Baseline)"
      : lead === "latest"
        ? "dem aktuellsten Einzelwert und seiner Einordnung"
        : "der Konstanz bzw. Streuung der Werte";
  return `ABWECHSLUNG: damit deine Karten nicht gleich klingen, darfst du diese mit ${angle} eröffnen — nur wenn die Daten diesen Blickwinkel wirklich tragen; nie erzwingen, nie einen Trend erfinden.`;
}

/**
 * Surface the computed data strength (n + recency) explicitly so the prose
 * and the UI confidence badge agree. The base prompt already tells the
 * model to be honest about thin data but leaves "few" undefined; this pins
 * the numbers the model would otherwise have to guess at.
 *
 * `points` is the number of daily buckets in the read window;
 * `newestDaysAgo` is how stale the most recent reading is (null when none).
 */
export function formatDataStrength(
  args: { points: number; newestDaysAgo: number | null },
  locale: Locale,
): string {
  const { points, newestDaysAgo } = args;
  const thin = points < 7;
  const stale = newestDaysAgo != null && newestDaysAgo > 7;
  if (locale === "en") {
    const recency =
      newestDaysAgo == null
        ? "no dated reading"
        : newestDaysAgo <= 0
          ? "latest reading today"
          : newestDaysAgo === 1
            ? "latest reading 1 day ago"
            : `latest reading ${newestDaysAgo} days ago`;
    const guidance = thin
      ? " — too few points for a reliable trend; hedge accordingly and avoid claiming a direction."
      : stale
        ? " — the data is going stale; note that the picture may be out of date."
        : "";
    return `DATA STRENGTH: ${points} day-buckets in the window, ${recency}.${guidance}`;
  }
  const recency =
    newestDaysAgo == null
      ? "kein datierter Wert"
      : newestDaysAgo <= 0
        ? "letzter Wert heute"
        : newestDaysAgo === 1
          ? "letzter Wert vor 1 Tag"
          : `letzter Wert vor ${newestDaysAgo} Tagen`;
  const guidance = thin
    ? " — zu wenige Punkte für einen belastbaren Trend; entsprechend vorsichtig formulieren, keine Richtung behaupten."
    : stale
      ? " — die Daten veralten; weise darauf hin, dass das Bild nicht mehr aktuell sein könnte."
      : "";
  return `DATENLAGE: ${points} Tages-Buckets im Fenster, ${recency}.${guidance}`;
}

/**
 * Repetition signal — how many of the most recent assessments in a row
 * carried the same direction/classification. Drives the model to vary or
 * escalate ("still steady, 3rd week running — let's look at a different
 * facet") instead of restating the same level verbatim.
 *
 * `repeatCount` is the run length of same-classification prior assessments
 * (0 when this is the first, or when the last assessment differed).
 */
export function formatRepetitionSignal(
  repeatCount: number,
  locale: Locale,
): string {
  if (repeatCount <= 0) {
    // No run to call out — stay silent so the block adds no noise.
    return "";
  }
  if (locale === "en") {
    return `REPETITION: you have already given a similar "no material change" assessment for this metric ${repeatCount} time(s) in a row. Do NOT restate the same level again. Acknowledge the continuity in one short clause ("still holding steady, ${repeatCount + 1} checks running") and then pivot to a DIFFERENT facet — consistency, time-of-day pattern, or a correlated metric — or, if nothing is genuinely actionable, say so plainly and skip the manufactured step.`;
  }
  return `WIEDERHOLUNG: du hast für diese Metrik bereits ${repeatCount}-mal in Folge eine ähnliche "keine wesentliche Änderung"-Einschätzung gegeben. Wiederhole NICHT erneut dasselbe Niveau. Benenne die Kontinuität in einem kurzen Nebensatz ("weiterhin stabil, ${repeatCount + 1} Checks in Folge") und wende dich dann einem ANDEREN Aspekt zu — Konstanz, Tageszeit-Muster oder einer korrelierten Metrik — oder sage, falls nichts wirklich umsetzbar ist, dies klar und lass den erzwungenen Schritt weg.`;
}

/**
 * Compute the "steady run" length from the graded series alone — how many
 * of the most recent weekly buckets in a row sit within a small band of the
 * user's own longer baseline. This is the grounded, computed-not-stored
 * proxy for "you've already noted this is steady N times": it derives the
 * repetition signal from the same graded data the model sees, so there is
 * no new persistence and no fragile prose-similarity matching.
 *
 * Returns 0 when the picture is NOT steady (most recent week deviates) or
 * when there are too few weekly buckets to judge — in both cases the
 * repetition block stays silent and the model proceeds normally.
 *
 * `weekly` / `monthly` are the graded-series slices (ascending: oldest →
 * newest). `bandFraction` is the relative tolerance around the baseline
 * mean that still counts as "no material change" (default 8 %).
 */
export function computeSteadyRun(
  weekly: ReadonlyArray<{ mean: number }> | undefined,
  monthly: ReadonlyArray<{ mean: number }> | undefined,
  bandFraction = 0.08,
): number {
  // Defensive: a graded slice can be absent on a degraded / stubbed series.
  // Treat a missing slice as no signal so the repetition block stays silent.
  if (!weekly || !monthly) return 0;
  if (weekly.length < 2) return 0;

  // Baseline: the longer-horizon mean the recent weeks are placed against.
  // Prefer the monthly means; fall back to the full weekly mean when no
  // monthly history exists yet.
  const baselineSource = monthly.length > 0 ? monthly : weekly;
  const baseline =
    baselineSource.reduce((sum, b) => sum + b.mean, 0) / baselineSource.length;
  if (!Number.isFinite(baseline) || baseline === 0) return 0;

  const band = Math.abs(baseline) * bandFraction;

  // Walk newest → oldest, counting consecutive weeks within the band.
  let run = 0;
  for (let i = weekly.length - 1; i >= 0; i--) {
    if (Math.abs(weekly[i].mean - baseline) <= band) {
      run += 1;
    } else {
      break;
    }
  }
  // A run of 1 is not yet repetition worth flagging; report 0 so the block
  // only fires once the steadiness has actually persisted.
  return run >= 2 ? run : 0;
}

/**
 * A single FDR-surviving correlation that involves the current metric,
 * reduced to the conservative descriptive `interpretation` string the
 * discovery engine already produced (never causal) plus its n and r for
 * the model to weigh.
 */
export interface RelevantCorrelation {
  interpretation: string;
  n: number;
  r: number;
}

/**
 * Format the cross-metric RELATIONS block. The interpretation strings are
 * passed VERBATIM — they are the engine's conservative, descriptive,
 * never-causal phrasings, already FDR-controlled. The instruction reminds
 * the model these are associations, optional to mention, and must never be
 * recast as causes or have their numbers altered.
 */
export function formatRelationsBlock(
  correlations: RelevantCorrelation[],
  locale: Locale,
): string {
  if (correlations.length === 0) return "";
  // Cap at two so the block never crowds out the metric's own grounding.
  const top = correlations.slice(0, 2);
  const lines = top.map(
    // eslint-disable-next-line healthlog/no-unlocalised-decimal -- text for the model, never shown to a person
    (c) => `- ${c.interpretation} (n=${c.n}, r=${c.r.toFixed(2)})`,
  );
  if (locale === "en") {
    return [
      "RELATIONS (statistically-screened associations in YOUR data involving this metric — descriptive, NEVER causal):",
      ...lines,
      'You MAY weave at most ONE of these in if it adds genuine insight, phrased as an "association" / "tends to go with" — never as a cause, and never alter the numbers. Skip them if the metric\'s own finding is the stronger story.',
    ].join("\n");
  }
  return [
    "ZUSAMMENHÄNGE (statistisch geprüfte Assoziationen in DEINEN Daten, die diese Metrik betreffen — beschreibend, NIE kausal):",
    ...lines,
    'Du DARFST höchstens EINEN davon einflechten, wenn er echten Mehrwert bringt — als "Zusammenhang" / "geht tendenziell einher mit" formuliert, nie als Ursache, und ohne die Zahlen zu verändern. Lass sie weg, wenn der eigene Befund der Metrik die stärkere Geschichte ist.',
  ].join("\n");
}

/**
 * Assemble the optional context blocks into one string the user prompt
 * appends after the previous-context block. Empty blocks drop out, so a
 * first-run thin-data metric with no correlations adds nothing.
 */
export function buildAssessmentContextBlock(
  args: {
    varietyLead: VarietyLead;
    dataStrength: { points: number; newestDaysAgo: number | null };
    repeatCount: number;
    relations: RelevantCorrelation[];
  },
  locale: Locale,
): string {
  const parts = [
    formatVarietyHint(args.varietyLead, locale),
    formatDataStrength(args.dataStrength, locale),
    formatRepetitionSignal(args.repeatCount, locale),
    formatRelationsBlock(args.relations, locale),
  ].filter((p) => p.trim().length > 0);
  return parts.join("\n\n");
}