@data-club/ai-hub 0.0.9 → 0.0.11

package/src/components/CacheBadge/index.tsx

@@ -1,245 +0,0 @@
-/**
- * `<CacheBadge />` — small per-message badge surfacing provider token
- * usage on an assistant bubble. Renders an inline icon + a compact
- * token count, with the full breakdown in a `title`-attribute tooltip
- * on hover.
- *
- * **What it shows.** Letta reports five things per assistant turn (via
- * `AIHubMessageUsage`): input tokens, output tokens, cache-read tokens
- * (prompt-cache HIT — provider charged ~0.1x), cache-write tokens
- * (provider charged ~1.25x, Anthropic only), reasoning tokens, and a
- * rolling context-window estimate.
- *
- * The headline number we show in the badge is the **cache-hit
- * percentage of the prompt** — `cache_read / (input + cache_read +
- * cache_write)`. That number is the single most useful at-a-glance
- * signal:
- *   - 0%  → cache is cold (cost is the worst case)
- *   - 80% → ~10x cheaper system prompt than a cold turn
- *
- * The full numbers live in the tooltip. We use the native `title`
- * attribute instead of a custom popover to keep the component
- * lightweight and dependency-free (no portals, no animation, no
- * focus management — perfect for a peripheral info chip).
- *
- * **When to render.** Only when the parent passes a `usage` prop with
- * at least one non-null number. Messages without a usage stamp (e.g.
- * historical conversations from before this feature shipped, or
- * tool-only assistant turns where Letta didn't report anything)
- * simply don't render the badge.
- *
- * Exported under `AIHub.CacheBadge` (re-exported via the namespace).
- *
- * @see AIHubMessageUsage in `../../types.ts`
- * @see SPECIFICATIONS.md §9.4 — `usage` SSE event
- */
-
-import type { ReactNode } from "react";
-
-import type { AIHubMessageUsage } from "../../types.js";
-
-/** BEM class names emitted by `<CacheBadge />`. */
-export interface CacheBadgeClassNames {
-  /** Outer span; `data-cache-state="hot|warm|cold|none"` for skinning. */
-  root: string;
-  /** The leading icon character (default 💾). */
-  icon: string;
-  /** The headline percentage label. */
-  label: string;
-}
-
-const DEFAULT_CLASS_NAMES: CacheBadgeClassNames = Object.freeze({
-  root: "data-club-ai-hub__cache-badge",
-  icon: "data-club-ai-hub__cache-badge__icon",
-  label: "data-club-ai-hub__cache-badge__label",
-}) as CacheBadgeClassNames;
-
-/** Localizable strings for the badge headline + tooltip. */
-export interface CacheBadgeTexts {
-  /** Headline shown when there's no cache info at all (e.g. providers that don't report). */
-  noCacheLabel: string;
-  /** Headline shown when this turn was a full cache miss (no tokens served from cache). */
-  missLabel: string;
-  /** Headline shown when this turn was a cache priming write — read=0 but write>0. */
-  writePrimingLabel: string;
-  /** Headline prefix for cache hits — full text is `${hitLabel} ${N}%`. */
-  hitLabel: string;
-  /** Tooltip line prefixes. Keep short — the tooltip is `title` only. */
-  hitTooltipLabel: string;
-  writeTooltipLabel: string;
-  inputLabel: string;
-  outputLabel: string;
-  reasoningLabel: string;
-  contextLabel: string;
-  totalLabel: string;
-}
-
-export const DEFAULT_TEXTS: CacheBadgeTexts = Object.freeze({
-  noCacheLabel: "no data",
-  missLabel: "MISS",
-  writePrimingLabel: "PRIMING",
-  hitLabel: "HIT",
-  hitTooltipLabel: "Cache hit",
-  writeTooltipLabel: "Cache write",
-  inputLabel: "Input",
-  outputLabel: "Output",
-  reasoningLabel: "Reasoning",
-  contextLabel: "Context",
-  totalLabel: "Total",
-}) as CacheBadgeTexts;
-
-/** Props for `<CacheBadge />`. */
-export interface CacheBadgeProps {
-  /** Per-message usage, as returned by `GET /sessions/:id/messages`. */
-  usage: AIHubMessageUsage;
-  /** Optional class-name overrides. */
-  classNames?: Partial<CacheBadgeClassNames>;
-  /** Optional text overrides (l10n). */
-  texts?: Partial<CacheBadgeTexts>;
-}
-
-/**
- * Computes the cache-hit ratio (0..1) over the prompt-side tokens.
- *
- * Denominator: `input + cache_read + cache_write` — every prompt
- * token the provider saw, regardless of whether it served from cache
- * or wrote new. We exclude `output` and `reasoning` because those
- * are completion-side and can't benefit from prompt caching.
- *
- * Exported so the test suite can assert numerically.
- */
-export function computeCacheHitRatio(usage: AIHubMessageUsage): number | null {
-  const read = usage.cache_read ?? 0;
-  const write = usage.cache_write ?? 0;
-  const input = usage.input ?? 0;
-  const denom = read + write + input;
-  if (denom === 0) return null;
-  return read / denom;
-}
-
-/**
- * Bucket the usage into a discrete state for skinning + label choice.
- *
- *   - `none`    — no prompt-side tokens reported at all (provider
- *                 didn't expose usage, or empty turn). Badge shows
- *                 the "no data" label.
- *   - `miss`    — full cache miss: `cache_read = 0` AND
- *                 `cache_write = 0` (or not reported). The provider
- *                 had to reinitialize the whole prompt. Badge shows
- *                 "MISS" in cold (grey) styling.
- *   - `priming` — `cache_read = 0` but `cache_write > 0`. This
- *                 turn's prompt was a CACHE WRITE — the provider
- *                 paid full price now and future turns benefit.
- *                 Anthropic only (the other providers don't report
- *                 writes). Badge shows "PRIMING".
- *   - `cold`    — `cache_read > 0` but ratio < 10%. Hit registered
- *                 but most of the prompt was new.
- *   - `warm`    — 10–60% of the prompt was cached.
- *   - `hot`     — 60%+ of the prompt was cached.
- */
-type CacheState = "none" | "miss" | "priming" | "cold" | "warm" | "hot";
-
-function bucketState(usage: AIHubMessageUsage, ratio: number | null): CacheState {
-  if (ratio === null) return "none";
-  if (ratio === 0) {
-    // No cache hit. Distinguish full-miss (nothing cached anywhere)
-    // from priming (we WROTE to the cache this turn — next turn will
-    // benefit). The latter is good news, the former is bad news, so
-    // the user-facing labels should differ.
-    return (usage.cache_write ?? 0) > 0 ? "priming" : "miss";
-  }
-  if (ratio >= 0.6) return "hot";
-  if (ratio >= 0.1) return "warm";
-  return "cold";
-}
-
-/** Formats a token count as a compact human-readable string: 1234 → 1.2k. */
-function formatTokens(n: number | null | undefined): string {
-  if (n === null || n === undefined) return "—";
-  if (n < 1000) return String(n);
-  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
-  return `${(n / 1_000_000).toFixed(2)}M`;
-}
-
-/** Builds the `title`-attribute tooltip text from the usage object. */
-function buildTooltip(usage: AIHubMessageUsage, texts: CacheBadgeTexts): string {
-  const lines: string[] = [];
-  if (usage.cache_read !== null && usage.cache_read !== undefined) {
-    lines.push(`${texts.hitTooltipLabel}: ${formatTokens(usage.cache_read)}`);
-  }
-  if (usage.cache_write !== null && usage.cache_write !== undefined) {
-    lines.push(`${texts.writeTooltipLabel}: ${formatTokens(usage.cache_write)}`);
-  }
-  if (usage.input !== null && usage.input !== undefined) {
-    lines.push(`${texts.inputLabel}: ${formatTokens(usage.input)}`);
-  }
-  if (usage.output !== null && usage.output !== undefined) {
-    lines.push(`${texts.outputLabel}: ${formatTokens(usage.output)}`);
-  }
-  if (usage.reasoning !== null && usage.reasoning !== undefined && usage.reasoning > 0) {
-    lines.push(`${texts.reasoningLabel}: ${formatTokens(usage.reasoning)}`);
-  }
-  if (usage.context !== null && usage.context !== undefined) {
-    lines.push(`${texts.contextLabel}: ${formatTokens(usage.context)}`);
-  }
-  if (usage.total !== null && usage.total !== undefined) {
-    lines.push(`${texts.totalLabel}: ${formatTokens(usage.total)}`);
-  }
-  return lines.join("\n");
-}
-
-/** Returns true when the usage object has at least one usable numeric field. */
-function hasAnyData(usage: AIHubMessageUsage): boolean {
-  return (
-    (usage.input ?? null) !== null ||
-    (usage.output ?? null) !== null ||
-    (usage.cache_read ?? null) !== null ||
-    (usage.cache_write ?? null) !== null ||
-    (usage.reasoning ?? null) !== null ||
-    (usage.context ?? null) !== null ||
-    (usage.total ?? null) !== null
-  );
-}
-
-export function CacheBadge({
-  usage,
-  classNames,
-  texts,
-}: CacheBadgeProps): ReactNode {
-  if (!hasAnyData(usage)) return null;
-  const cls: CacheBadgeClassNames = { ...DEFAULT_CLASS_NAMES, ...(classNames ?? {}) };
-  const t: CacheBadgeTexts = { ...DEFAULT_TEXTS, ...(texts ?? {}) };
-
-  const ratio = computeCacheHitRatio(usage);
-  const state = bucketState(usage, ratio);
-  // Headline label — varies by state so the user gets an immediate
-  // diagnostic signal at-a-glance.
-  let headline: string;
-  if (state === "none") {
-    headline = t.noCacheLabel;
-  } else if (state === "miss") {
-    headline = t.missLabel;
-  } else if (state === "priming") {
-    headline = t.writePrimingLabel;
-  } else {
-    // hot / warm / cold — ratio is guaranteed non-null here.
-    headline = `${t.hitLabel} ${Math.round((ratio ?? 0) * 100)}%`;
-  }
-  const tooltip = buildTooltip(usage, t);
-
-  return (
-    <span
-      className={cls.root}
-      data-testid="cache-badge"
-      data-cache-state={state}
-      title={tooltip}
-      role="status"
-      aria-label={tooltip}
-    >
-      <span className={cls.icon} aria-hidden="true">
-        💾
-      </span>
-      <span className={cls.label}>{headline}</span>
-    </span>
-  );
-}