@tokcalc/mcp-server 0.1.0 → 0.1.2

package/src/components/azure-live-pricing.tsx

@@ -0,0 +1,185 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+import { RefreshCw, Zap, AlertTriangle } from "lucide-react";
+import { track } from "@/lib/track";
+
+interface AzurePrice {
+  gpu: string;
+  sku: string;
+  price: number;
+  region: string;
+  retrievedAt: string;
+}
+
+interface AzureApiResponse {
+  source: string;
+  cached: boolean;
+  retrievedAt?: string;
+  count?: number;
+  prices?: AzurePrice[];
+  error?: string;
+}
+
+export function AzureLivePricing() {
+  const [data, setData] = useState<AzureApiResponse | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchPrices = async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await fetch("/api/pricing/azure");
+      if (!res.ok) {
+        const errData = await res.json().catch(() => ({}));
+        throw new Error(errData.error || `HTTP ${res.status}`);
+      }
+      const json = (await res.json()) as AzureApiResponse;
+      setData(json);
+      track("fetched_live_pricing", { provider: "azure", count: json.count });
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Failed to fetch Azure pricing");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // Auto-fetch on mount
+  useEffect(() => {
+    fetchPrices();
+  }, []);
+
+  // Find cheapest price per GPU
+  const cheapestPerGpu = (() => {
+    if (!data?.prices) return [];
+    const seen = new Map<string, AzurePrice>();
+    for (const p of data.prices) {
+      if (!seen.has(p.gpu) || seen.get(p.gpu)!.price > p.price) {
+        seen.set(p.gpu, p);
+      }
+    }
+    return Array.from(seen.values()).sort((a, b) => a.price - b.price);
+  })();
+
+  // Calculate "as of" label
+  const asOfLabel = (() => {
+    if (!data?.retrievedAt) return null;
+    const ageMs = Date.now() - new Date(data.retrievedAt).getTime();
+    if (ageMs < 60000) return "just now";
+    if (ageMs < 3600000) return `${Math.floor(ageMs / 60000)}m ago`;
+    return `${Math.floor(ageMs / 3600000)}h ago`;
+  })();
+
+  return (
+    <Card className="border-emerald-500/30 shadow-sm">
+      <CardHeader className="pb-3">
+        <div className="flex items-center justify-between">
+          <div>
+            <CardTitle className="text-sm flex items-center gap-2">
+              <Zap className="size-4 text-emerald-500" />
+              Live Azure GPU pricing
+              <Badge variant="outline" className="text-[9px] gap-1 ml-1">
+                <span className="size-1.5 rounded-full bg-emerald-500 animate-pulse" />
+                LIVE
+              </Badge>
+            </CardTitle>
+            <CardDescription className="text-xs mt-1">
+              Fetched from Azure Retail Prices API (public, unauthenticated).
+              {asOfLabel && ` Last updated ${asOfLabel}.`}
+            </CardDescription>
+          </div>
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={fetchPrices}
+            disabled={loading}
+            className="gap-1.5 h-8"
+          >
+            <RefreshCw className={`size-3.5 ${loading ? "animate-spin" : ""}`} />
+            <span className="text-xs">Refresh</span>
+          </Button>
+        </div>
+      </CardHeader>
+      <CardContent>
+        {loading && !data && (
+          <div className="flex items-center justify-center py-8 text-xs text-muted-foreground">
+            <RefreshCw className="size-4 animate-spin mr-2" />
+            Fetching live Azure prices...
+          </div>
+        )}
+
+        {error && (
+          <div className="flex items-start gap-2 p-3 rounded-md border border-amber-500/30 bg-amber-500/5 text-xs">
+            <AlertTriangle className="size-3.5 text-amber-500 shrink-0 mt-0.5" />
+            <div>
+              <p className="font-medium text-amber-600 dark:text-amber-400">
+                Couldn&apos;t fetch live prices
+              </p>
+              <p className="text-muted-foreground mt-0.5">{error}</p>
+              <p className="text-muted-foreground mt-1">
+                Static estimates from tokcalc&apos;s catalog are shown below.
+              </p>
+            </div>
+          </div>
+        )}
+
+        {data?.error && (
+          <div className="flex items-start gap-2 p-3 rounded-md border border-amber-500/30 bg-amber-500/5 text-xs">
+            <AlertTriangle className="size-3.5 text-amber-500 shrink-0 mt-0.5" />
+            <p className="text-muted-foreground">{data.error}</p>
+          </div>
+        )}
+
+        {cheapestPerGpu.length > 0 && (
+          <div className="overflow-x-auto">
+            <table className="w-full text-xs">
+              <thead className="bg-muted/40 text-[10px] uppercase">
+                <tr>
+                  <th className="text-left px-3 py-1.5">GPU</th>
+                  <th className="text-left px-3 py-1.5">Azure SKU</th>
+                  <th className="text-right px-3 py-1.5">$/GPU-hr (cheapest)</th>
+                  <th className="text-left px-3 py-1.5">Region</th>
+                  <th className="text-left px-3 py-1.5">As of</th>
+                </tr>
+              </thead>
+              <tbody>
+                {cheapestPerGpu.map((p, i) => (
+                  <tr key={i} className="border-t border-border/40 hover:bg-muted/20">
+                    <td className="px-3 py-1.5 font-medium">{p.gpu}</td>
+                    <td className="px-3 py-1.5 text-muted-foreground font-mono text-[10px]">{p.sku}</td>
+                    <td className="px-3 py-1.5 text-right font-mono text-emerald-500 font-semibold">
+                      ${p.price}/hr
+                    </td>
+                    <td className="px-3 py-1.5 text-muted-foreground">{p.region}</td>
+                    <td className="px-3 py-1.5 text-muted-foreground text-[10px]">{asOfLabel}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+            <p className="text-[10px] text-muted-foreground mt-2 leading-relaxed">
+              Per-GPU price derived from Azure instance price ÷ GPU count.
+              On-demand rates only (spot/reserved excluded).
+              Prices may vary by region, availability zone, and commitment.
+              Source: <a
+                href="https://prices.azure.com/api/retail/prices"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-emerald-500 hover:underline"
+              >Azure Retail Prices API ↗</a>
+            </p>
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/src/components/benchmark-import.tsx

@@ -0,0 +1,340 @@
+"use client";
+
+import { useState } from "react";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { Textarea } from "@/components/ui/textarea";
+import { Badge } from "@/components/ui/badge";
+import { AlertTriangle, CheckCircle2, Upload, Beaker, Download } from "lucide-react";
+import {
+  vllmParser,
+} from "@/lib/benchmark-parser-vllm";
+import { sglangParser } from "@/lib/benchmark-parser-sglang";
+import { trtllmParser } from "@/lib/benchmark-parser-trtllm";
+import { tokcalcStandardParser, BENCHMARK_TEMPLATE } from "@/lib/benchmark-parser-tokcalc";
+import type {
+  BenchmarkRecord,
+  BenchmarkParser,
+  CalibrationResult,
+} from "@/lib/benchmark-schema";
+import {
+  formatCalibrationVerdict,
+  generateBenchmarkId,
+} from "@/lib/benchmark-schema";
+import type { CalcResult } from "@/lib/token-calc";
+import { fmtTokens, fmtMs } from "@/lib/token-calc";
+import { track } from "@/lib/track";
+
+interface BenchmarkImportProps {
+  /** The theoretical estimate from tokcalc's formulas */
+  estimate: CalcResult;
+  /** Current model name (for matching) */
+  modelName: string;
+  /** Current GPU name (for matching) */
+  gpuName: string;
+}
+
+export function BenchmarkImport({ estimate, modelName, gpuName }: BenchmarkImportProps) {
+  const [rawText, setRawText] = useState("");
+  const [record, setRecord] = useState<BenchmarkRecord | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [expanded, setExpanded] = useState(false);
+
+  const handleParse = () => {
+    setError(null);
+    if (!rawText.trim()) {
+      setError("Paste a benchmark JSON output first.");
+      return;
+    }
+
+    // Try parsers — order matters: most-specific first, most-generic last.
+    // TRT-LLM has unique field names (first_token_latency_avg, inter_token_latency_avg)
+    // SGLang has unique field names (total_throughput, ttft_avg, itl_avg)
+    // vLLM is most generic (output_throughput, mean_ttft_ms) — try last
+    const parsers: BenchmarkParser[] = [trtllmParser, sglangParser, vllmParser, tokcalcStandardParser];
+    for (const parser of parsers) {
+      if (parser.detect(rawText)) {
+        const parsed = parser.parse(rawText);
+        if (parsed) {
+          setRecord(parsed);
+          track("imported_benchmark", {
+            engine: parsed.serving_engine,
+            model: parsed.model_display_name,
+            throughput: parsed.output_token_throughput_tps,
+            parser: parser.name,
+          });
+          setExpanded(true);
+          return;
+        }
+      }
+    }
+
+    setError(
+      "Couldn't parse this as vLLM, SGLang, or TensorRT-LLM benchmark JSON. " +
+      "Make sure you're pasting the raw JSON output from the benchmark script. " +
+      "Supported formats: vLLM benchmark_serving.py, SGLang benchmark, TRT-LLM benchmark_serving.py."
+    );
+  };
+
+  // Compute calibration if we have both estimate and observed data
+  const calibration: CalibrationResult | null = record
+    ? computeCalibration(estimate, record)
+    : null;
+
+  const verdict = calibration ? formatCalibrationVerdict(calibration.verdict) : null;
+
+  return (
+    <Card className="border-border/60 shadow-sm">
+      <CardHeader className="pb-3">
+        <CardTitle className="text-sm flex items-center gap-2">
+          <Beaker className="size-4 text-emerald-500" />
+          Observed benchmark — calibrate the formula
+        </CardTitle>
+        <CardDescription className="text-xs">
+          Paste a vLLM benchmark JSON output to see how tokcalc&apos;s theoretical estimates compare to real-world measured performance.
+          The calibration verdict shows whether the formula is accurate, too conservative, or too optimistic.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-3">
+        {!record && !expanded && (
+          <div className="flex flex-col sm:flex-row gap-2">
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => setExpanded(true)}
+              className="flex-1 gap-1.5"
+            >
+              <Upload className="size-3.5" />
+              Import a benchmark result
+            </Button>
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => {
+                const blob = new Blob([BENCHMARK_TEMPLATE], { type: "application/json" });
+                const url = URL.createObjectURL(blob);
+                const a = document.createElement("a");
+                a.href = url;
+                a.download = "tokcalc-benchmark-template.json";
+                document.body.appendChild(a);
+                a.click();
+                document.body.removeChild(a);
+                URL.revokeObjectURL(url);
+                track("downloaded_benchmark_template");
+              }}
+              className="flex-1 gap-1.5"
+            >
+              <Download className="size-3.5" />
+              Download template
+            </Button>
+          </div>
+        )}
+
+        {expanded && !record && (
+          <>
+            <div>
+              <Textarea
+                placeholder={`Paste JSON from:\n- vllm benchmark_serving.py output\n- SGLang benchmark output\n- TensorRT-LLM benchmark_serving.py output\n- tokcalc community template (download above)\n\nOr click "Download template" to get a structured JSON you can fill in manually.`}
+                value={rawText}
+                onChange={(e) => setRawText(e.target.value)}
+                className="font-mono text-xs min-h-[160px] resize-y"
+              />
+            </div>
+            {error && (
+              <div className="text-[11px] text-amber-600 dark:text-amber-400 flex items-start gap-1.5">
+                <AlertTriangle className="size-3.5 shrink-0 mt-0.5" />
+                <span>{error}</span>
+              </div>
+            )}
+            <div className="flex gap-2">
+              <Button size="sm" onClick={handleParse} className="gap-1.5">
+                <Beaker className="size-3.5" />
+                Parse &amp; calibrate
+              </Button>
+              <Button
+                size="sm"
+                variant="ghost"
+                onClick={() => { setExpanded(false); setRawText(""); setError(null); }}
+              >
+                Cancel
+              </Button>
+            </div>
+            <p className="text-[10px] text-muted-foreground leading-relaxed">
+              Your benchmark data stays in your browser — nothing is sent to a server.
+              SGLang and TensorRT-LLM parsers are on the roadmap.
+            </p>
+          </>
+        )}
+
+        {record && calibration && verdict && (
+          <div className="space-y-3">
+            {/* Calibration verdict */}
+            <div className={`flex items-start gap-3 p-3 rounded-md border ${
+              calibration.verdict === "validated"
+                ? "border-emerald-500/40 bg-emerald-500/5"
+                : calibration.verdict === "insufficient_data"
+                  ? "border-border/60 bg-muted/20"
+                  : "border-amber-500/40 bg-amber-500/5"
+            }`}>
+              {calibration.verdict === "validated" ? (
+                <CheckCircle2 className="size-4 text-emerald-500 shrink-0 mt-0.5" />
+              ) : (
+                <AlertTriangle className="size-4 text-amber-500 shrink-0 mt-0.5" />
+              )}
+              <div className="text-xs">
+                <div className={`font-medium ${verdict.color}`}>
+                  {verdict.label}
+                </div>
+                <div className="text-muted-foreground mt-0.5 leading-relaxed">
+                  {verdict.description}
+                </div>
+                {calibration.calibrationErrors.throughputErrorPct !== undefined && (
+                  <div className="mt-1.5 font-mono text-[11px]">
+                    Throughput: estimated <strong className="text-foreground">{fmtTokens(estimate.decodeTokensPerSec)} tok/s</strong> vs observed <strong className="text-foreground">{fmtTokens(record.output_token_throughput_tps)} tok/s</strong>
+                    {" "}→ <span className={Math.abs(calibration.calibrationErrors.throughputErrorPct) < 20 ? "text-emerald-500" : "text-amber-500"}>
+                      {calibration.calibrationErrors.throughputErrorPct > 0 ? "+" : ""}{calibration.calibrationErrors.throughputErrorPct.toFixed(1)}% error
+                    </span>
+                  </div>
+                )}
+                {calibration.calibrationErrors.ttftErrorPct !== undefined && (
+                  <div className="mt-1 font-mono text-[11px]">
+                    TTFT: estimated <strong className="text-foreground">{fmtMs(estimate.ttftMs)}</strong> vs observed <strong className="text-foreground">{fmtMs(record.ttft_mean_ms || 0)}</strong>
+                    {" "}→ <span className={Math.abs(calibration.calibrationErrors.ttftErrorPct) < 20 ? "text-emerald-500" : "text-amber-500"}>
+                      {calibration.calibrationErrors.ttftErrorPct > 0 ? "+" : ""}{calibration.calibrationErrors.ttftErrorPct.toFixed(1)}% error
+                    </span>
+                  </div>
+                )}
+                {calibration.calibrationErrors.itlErrorPct !== undefined && (
+                  <div className="mt-1 font-mono text-[11px]">
+                    ITL: estimated <strong className="text-foreground">{fmtMs(estimate.itlMs)}</strong> vs observed <strong className="text-foreground">{fmtMs(record.itl_mean_ms || 0)}</strong>
+                    {" "}→ <span className={Math.abs(calibration.calibrationErrors.itlErrorPct) < 20 ? "text-emerald-500" : "text-amber-500"}>
+                      {calibration.calibrationErrors.itlErrorPct > 0 ? "+" : ""}{calibration.calibrationErrors.itlErrorPct.toFixed(1)}% error
+                    </span>
+                  </div>
+                )}
+              </div>
+            </div>
+
+            {/* Observed metrics detail */}
+            <div className="grid grid-cols-2 sm:grid-cols-4 gap-3 text-sm">
+              <div className="space-y-0.5">
+                <div className="text-[10px] uppercase tracking-wider text-muted-foreground">Observed throughput</div>
+                <div className="font-mono text-sm font-medium">{fmtTokens(record.output_token_throughput_tps)} tok/s</div>
+                <div className="text-[10px] text-muted-foreground">{record.request_throughput_rps?.toFixed(1) || "—"} req/s</div>
+              </div>
+              <div className="space-y-0.5">
+                <div className="text-[10px] uppercase tracking-wider text-muted-foreground">TTFT (mean / p99)</div>
+                <div className="font-mono text-sm font-medium">{fmtMs(record.ttft_mean_ms || 0)}</div>
+                <div className="text-[10px] text-muted-foreground">p99: {fmtMs(record.ttft_p99_ms || 0)}</div>
+              </div>
+              <div className="space-y-0.5">
+                <div className="text-[10px] uppercase tracking-wider text-muted-foreground">ITL (mean / p99)</div>
+                <div className="font-mono text-sm font-medium">{fmtMs(record.itl_mean_ms || 0)}</div>
+                <div className="text-[10px] text-muted-foreground">p99: {fmtMs(record.itl_p99_ms || 0)}</div>
+              </div>
+              <div className="space-y-0.5">
+                <div className="text-[10px] uppercase tracking-wider text-muted-foreground">Config</div>
+                <div className="font-mono text-[11px] font-medium">{record.gpu_count}×{record.accelerator_model.split(" ")[0]}</div>
+                <div className="text-[10px] text-muted-foreground">{record.serving_engine} v{record.engine_version.slice(0, 6)}</div>
+              </div>
+            </div>
+
+            {/* Provenance */}
+            <div className="text-[10px] text-muted-foreground border-t border-border/40 pt-2">
+              <strong className="text-foreground">Source:</strong> {record.source_name} ({record.confidence_tier.replace(/_/g, " ")}) ·
+              {" "}{record.request_count.toLocaleString()} requests · {record.input_tokens_mean} in / {record.output_tokens_mean} out tokens ·
+              {" "}concurrency {record.concurrency} ·
+              {" "}{record.model_display_name} · {record.quantization_format} ·
+              {" "}<a href={record.source_url} target="_blank" rel="noopener noreferrer" className="text-emerald-500 hover:underline">source ↗</a>
+            </div>
+
+            <Button
+              size="sm"
+              variant="ghost"
+              onClick={() => { setRecord(null); setRawText(""); setExpanded(false); }}
+              className="text-xs"
+            >
+              Import a different benchmark
+            </Button>
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+
+/* ---------- Calibration computation ---------- */
+
+function computeCalibration(
+  estimate: CalcResult,
+  observed: BenchmarkRecord,
+): CalibrationResult {
+  const errors: CalibrationResult["calibrationErrors"] = {};
+
+  // Throughput calibration (if observed has throughput)
+  if (observed.output_token_throughput_tps && estimate.decodeTokensPerSec > 0) {
+    errors.throughputErrorPct =
+      ((observed.output_token_throughput_tps - estimate.decodeTokensPerSec) / estimate.decodeTokensPerSec) * 100;
+  }
+
+  // TTFT calibration (if observed has mean TTFT)
+  if (observed.ttft_mean_ms && estimate.ttftMs > 0) {
+    errors.ttftErrorPct =
+      ((observed.ttft_mean_ms - estimate.ttftMs) / estimate.ttftMs) * 100;
+  }
+
+  // ITL calibration (if observed has mean ITL)
+  if (observed.itl_mean_ms && estimate.itlMs > 0) {
+    errors.itlErrorPct =
+      ((observed.itl_mean_ms - estimate.itlMs) / estimate.itlMs) * 100;
+  }
+
+  // Memory calibration (if observed has peak GPU memory)
+  if (observed.gpu_memory_peak_gb && estimate.totalVramNeededGb > 0) {
+    errors.memoryErrorPct =
+      ((observed.gpu_memory_peak_gb - estimate.totalVramNeededGb) / estimate.totalVramNeededGb) * 100;
+  }
+
+  // Determine verdict
+  let verdict: CalibrationResult["verdict"] = "insufficient_data";
+  const errorValues = Object.values(errors).filter((v) => v !== undefined) as number[];
+
+  if (errorValues.length >= 2) {
+    const maxAbsError = Math.max(...errorValues.map((v) => Math.abs(v)));
+    if (maxAbsError < 20) {
+      verdict = "validated";
+    } else if (maxAbsError > 0) {
+      // If most errors are positive (observed > estimated), we underestimated
+      // If most are negative (observed < estimated), we overestimated
+      const avgError = errorValues.reduce((a, b) => a + b, 0) / errorValues.length;
+      verdict = avgError > 0 ? "underestimated" : "overestimated";
+    }
+  }
+
+  return {
+    estimated: {
+      decodeTokensPerSec: estimate.decodeTokensPerSec,
+      aggregateTokensPerSec: estimate.aggregateTokensPerSec,
+      prefillTokensPerSec: estimate.prefillTokensPerSec,
+      ttftMs: estimate.ttftMs,
+      itlMs: estimate.itlMs,
+      modelSizeGb: estimate.modelSizeGb,
+    },
+    observed: {
+      outputTokenThroughputTps: observed.output_token_throughput_tps,
+      ttftMeanMs: observed.ttft_mean_ms,
+      ttftP95Ms: observed.ttft_p95_ms,
+      itlMeanMs: observed.itl_mean_ms,
+      itlP95Ms: observed.itl_p95_ms,
+      gpuMemoryPeakGb: observed.gpu_memory_peak_gb,
+    },
+    calibrationErrors: errors,
+    verdict,
+  };
+}

package/src/components/confidence-badge.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import type { Confidence } from "@/lib/token-calc";
+
+const CONFIDENCE_CONFIG: Record<
+  Confidence,
+  { color: string; label: string; description: string }
+> = {
+  measured: {
+    color: "bg-emerald-500",
+    label: "Measured",
+    description:
+      "Sourced directly from official specs, model cards, API pricing pages, or HuggingFace config.json. Highest confidence — verify at the cited source URL.",
+  },
+  modeled: {
+    color: "bg-emerald-400",
+    label: "Modeled",
+    description:
+      "Derived from a physics-based formula with cited sources (e.g., decode tok/s = HBM_BW × η_mem × quant_eff / model_size). Conditional on assumptions — see formula docs.",
+  },
+  inferred: {
+    color: "bg-amber-500",
+    label: "Inferred",
+    description:
+      "Derived from a heuristic with known error bars (e.g., continuous batching multiplier default 1.5×, long-context attention O(N²) correction). Treat as ballpark, not exact.",
+  },
+  "user-supplied": {
+    color: "bg-zinc-400",
+    label: "User-supplied",
+    description: "You provided this value directly. We trust your input.",
+  },
+};
+
+export function ConfidenceBadge({
+  confidence,
+  className,
+}: {
+  confidence: Confidence;
+  className?: string;
+}) {
+  const config = CONFIDENCE_CONFIG[confidence];
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          aria-label={`Confidence: ${config.label}`}
+          className={`inline-flex items-center gap-1 text-[9px] font-medium uppercase tracking-wider text-muted-foreground hover:text-foreground transition-colors ${className ?? ""}`}
+        >
+          <span className={`size-1.5 rounded-full ${config.color}`} />
+          {config.label}
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="top" className="max-w-[280px] text-xs leading-relaxed">
+        <div className="font-semibold mb-1">{config.label}</div>
+        <div className="text-muted-foreground">{config.description}</div>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+/** Compact version — just the dot, no label. Use in tight spaces like headline cards. */
+export function ConfidenceDot({
+  confidence,
+  className,
+}: {
+  confidence: Confidence;
+  className?: string;
+}) {
+  const config = CONFIDENCE_CONFIG[confidence];
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          aria-label={`Confidence: ${config.label}`}
+          className={`inline-flex items-center justify-center ${className ?? ""}`}
+        >
+          <span className={`size-1.5 rounded-full ${config.color} hover:scale-125 transition-transform`} />
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="top" className="max-w-[280px] text-xs leading-relaxed">
+        <div className="font-semibold mb-1">{config.label}</div>
+        <div className="text-muted-foreground">{config.description}</div>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+/** Legend block — show at the bottom of the Calculator tab + in the glossary. */
+export function ConfidenceLegend() {
+  return (
+    <div className="rounded-md border border-border/60 bg-muted/20 p-3">
+      <div className="text-[10px] uppercase tracking-wider text-muted-foreground font-semibold mb-2">
+        Confidence levels
+      </div>
+      <div className="grid grid-cols-2 sm:grid-cols-4 gap-2 text-[11px]">
+        {(Object.keys(CONFIDENCE_CONFIG) as Confidence[]).map((key) => {
+          const config = CONFIDENCE_CONFIG[key];
+          return (
+            <div key={key} className="flex items-start gap-1.5">
+              <span className={`size-1.5 rounded-full ${config.color} mt-1 shrink-0`} />
+              <div>
+                <div className="font-medium text-foreground">{config.label}</div>
+                <div className="text-muted-foreground text-[10px] leading-snug mt-0.5">
+                  {config.description.split(". ")[0]}.
+                </div>
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}