@absolutejs/rag 0.0.16 → 0.0.17

package/dist/presentation/ui.js

@@ -11221,6 +11221,210 @@ var summarizeRAGRetrievalComparison = (entries) => ({
   bestByLowestRuntimeCandidateBudgetExhaustedCases: selectComparisonEntryByLowestTraceMetric(entries, "retrievalId", "runtimeCandidateBudgetExhaustedCases"),
   bestByLowestRuntimeUnderfilledTopKCases: selectComparisonEntryByLowestTraceMetric(entries, "retrievalId", "runtimeUnderfilledTopKCases")
 });
+// src/presentation/htmxCitationFragments.ts
+var formatScore = (value) => Number.isFinite(value) ? value.toFixed(3) : "0.000";
+var buildSearchTargetId = (prefix, value) => {
+  const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return `${prefix}-${normalized || "item"}`;
+};
+var buildSourceSummarySectionGroups = (summaries) => {
+  const groups = new Map;
+  for (const summary of summaries ?? []) {
+    const label = summary.contextLabel ?? summary.label;
+    const id = buildSearchTargetId("source-summary-section", label);
+    const existing = groups.get(id);
+    if (existing) {
+      existing.summaries.push(summary);
+      existing.summary = `${existing.summaries.length} evidence summar${existing.summaries.length === 1 ? "y" : "ies"}`;
+      continue;
+    }
+    groups.set(id, {
+      id,
+      label,
+      targetId: id,
+      summary: "1 evidence summary",
+      summaries: [summary]
+    });
+  }
+  return [...groups.values()].sort((left, right) => {
+    const leftScore = Math.max(...left.summaries.map((summary) => summary.bestScore));
+    const rightScore = Math.max(...right.summaries.map((summary) => summary.bestScore));
+    return rightScore - leftScore;
+  });
+};
+var buildGroundingReferenceGroups = (references) => {
+  const groups = new Map;
+  for (const reference of references ?? []) {
+    const label = reference.contextLabel ?? reference.label ?? reference.source ?? reference.chunkId;
+    const id = buildSearchTargetId("grounding-reference-section", label);
+    const existing = groups.get(id);
+    if (existing) {
+      existing.references.push(reference);
+      existing.summary = `${existing.references.length} grounding reference${existing.references.length === 1 ? "" : "s"}`;
+      continue;
+    }
+    groups.set(id, {
+      id,
+      label,
+      targetId: id,
+      summary: "1 grounding reference",
+      references: [reference]
+    });
+  }
+  return [...groups.values()].sort((left, right) => {
+    const leftScore = Math.max(...left.references.map((reference) => reference.score));
+    const rightScore = Math.max(...right.references.map((reference) => reference.score));
+    return rightScore - leftScore;
+  });
+};
+var buildCitationGroups = (citations) => {
+  const groups = new Map;
+  for (const citation of citations ?? []) {
+    const label = citation.contextLabel ?? citation.label ?? citation.source ?? citation.chunkId;
+    const id = buildSearchTargetId("citation-section", label);
+    const existing = groups.get(id);
+    if (existing) {
+      existing.citations.push(citation);
+      existing.summary = `${existing.citations.length} citation${existing.citations.length === 1 ? "" : "s"}`;
+      continue;
+    }
+    groups.set(id, {
+      id,
+      label,
+      targetId: id,
+      summary: "1 citation",
+      citations: [citation]
+    });
+  }
+  return [...groups.values()].sort((left, right) => {
+    const leftScore = Math.max(...left.citations.map((citation) => citation.score));
+    const rightScore = Math.max(...right.citations.map((citation) => citation.score));
+    return rightScore - leftScore;
+  });
+};
+var formatCitationLabel = (citation) => [citation.label, citation.contextLabel, citation.locatorLabel].filter(Boolean).join(" \xB7 ");
+var formatCitationSummary = (citation) => citation.source ?? citation.title ?? citation.chunkId;
+var formatCitationExcerpt = (citation) => citation.excerpt || citation.text;
+var formatEvidenceDetailLine = (label, value) => value && value.length > 0 ? `${label}: ${value}` : "";
+var formatEvidenceContextLine = (contextLabel, locatorLabel) => {
+  const value = [locatorLabel, contextLabel].filter((entry) => Boolean(entry && entry.length > 0)).join(" \xB7 ");
+  return value.length > 0 ? `location: ${value}` : "";
+};
+var formatSourceSummaryDetails = (summary) => [
+  `best score: ${formatScore(summary.bestScore)}`,
+  `coverage: ${summary.count} chunk(s) \xB7 citations ${summary.citationNumbers.map((value) => `[${value}]`).join(" ") || "none"}`,
+  formatEvidenceContextLine(summary.contextLabel, summary.locatorLabel),
+  formatEvidenceDetailLine("provenance", summary.provenanceLabel)
+].filter((value) => value.length > 0);
+var formatCitationDetails = (citation) => [
+  formatEvidenceDetailLine("evidence", citation.source ?? citation.title ?? citation.chunkId),
+  formatEvidenceContextLine(citation.contextLabel, citation.locatorLabel),
+  formatEvidenceDetailLine("provenance", citation.provenanceLabel),
+  `score: ${formatScore(citation.score)}`
+].filter((value) => value.length > 0);
+var formatSectionDiagnosticPercent = (value) => typeof value === "number" ? `${Math.round(value * 100)}%` : null;
+var formatSectionDiagnosticReason = (reason) => reason.replaceAll("_", " ");
+var formatSectionDiagnosticStage = (stage) => stage.replaceAll("_", " ");
+var formatSectionDiagnosticWeightReason = (reason) => ({
+  final_stage_concentration: "final stage concentrated on this section",
+  final_stage_dominant_within_parent: "final stage stayed ahead inside its parent",
+  rerank_preserved_lead: "rerank kept this section in front",
+  stage_runner_up_pressure: "runner-up stayed close in this stage",
+  stage_expanded: "this section expanded in this stage",
+  stage_held: "this section held steady in this stage",
+  stage_narrowed: "this section narrowed in this stage"
+})[reason] ?? reason.replaceAll("_", " ");
+var formatSectionQueryAttributionReason = (reason) => ({
+  base_query_only: "came only from the base query",
+  transformed_query_only: "came only from the transformed query",
+  variant_only: "came only from query variants",
+  transform_introduced: "the transformed query introduced this section",
+  variant_supported: "query variants reinforced this section",
+  mixed_query_sources: "multiple query forms contributed"
+})[reason] ?? reason.replaceAll("_", " ");
+var formatSectionDiagnosticChannels = (diagnostic) => `Channels \xB7 hybrid ${diagnostic.hybridHits} \xB7 vector ${diagnostic.vectorHits} \xB7 lexical ${diagnostic.lexicalHits}`;
+var formatSectionDiagnosticAttributionFocus = (diagnostic) => {
+  const mode = diagnostic.queryAttribution?.mode ?? "mixed";
+  const label = mode === "primary" ? "Attribution \xB7 base-query-only" : mode === "transformed" ? "Attribution \xB7 transformed-only" : mode === "variant" ? "Attribution \xB7 variant-only" : "Attribution \xB7 mixed";
+  const parts = [label];
+  if ((diagnostic.queryAttribution?.primaryHits ?? 0) > 0)
+    parts.push(`base ${diagnostic.queryAttribution?.primaryHits}`);
+  if ((diagnostic.queryAttribution?.transformedHits ?? 0) > 0)
+    parts.push(`transformed ${diagnostic.queryAttribution?.transformedHits}`);
+  if ((diagnostic.queryAttribution?.variantHits ?? 0) > 0)
+    parts.push(`variant ${diagnostic.queryAttribution?.variantHits}`);
+  return parts.join(" \xB7 ");
+};
+var formatSectionDiagnosticPipeline = (diagnostic) => {
+  const requestedMode = diagnostic.requestedMode ?? diagnostic.retrievalMode ?? "n/a";
+  const selectedMode = diagnostic.retrievalMode ?? "n/a";
+  const routeLabel = diagnostic.routingLabel ?? "default route";
+  const transformLabel = diagnostic.queryTransformLabel ?? "no transform";
+  return `Mode ${selectedMode} \xB7 requested ${requestedMode} \xB7 route ${routeLabel} \xB7 transform ${transformLabel} \xB7 rerank ${diagnostic.rerankApplied ? "on" : "off"} \xB7 source balance ${diagnostic.sourceBalanceApplied ? "on" : "off"} \xB7 threshold ${diagnostic.scoreThresholdApplied ? "on" : "off"} \xB7 query ${diagnostic.queryAttribution?.mode ?? "n/a"}`;
+};
+var formatSectionDiagnosticStageFlow = (diagnostic) => diagnostic.stageCounts.length > 0 ? `Stage flow \xB7 ${diagnostic.stageCounts.map((entry) => `${formatSectionDiagnosticStage(entry.stage)} ${entry.count}`).join(" \u2192 ")}` : null;
+var formatSectionDiagnosticStageBounds = (diagnostic) => {
+  const parts = [];
+  if (diagnostic.firstSeenStage)
+    parts.push(`first seen ${formatSectionDiagnosticStage(diagnostic.firstSeenStage)}`);
+  if (diagnostic.lastSeenStage)
+    parts.push(`last seen ${formatSectionDiagnosticStage(diagnostic.lastSeenStage)}`);
+  if (diagnostic.peakStage)
+    parts.push(`peak ${formatSectionDiagnosticStage(diagnostic.peakStage)} ${diagnostic.peakCount}`);
+  const finalRetention = formatSectionDiagnosticPercent(diagnostic.finalRetentionRate);
+  if (finalRetention)
+    parts.push(`final retention ${finalRetention}`);
+  if (typeof diagnostic.dropFromPeak === "number")
+    parts.push(`drop from peak ${diagnostic.dropFromPeak}`);
+  return parts.length > 0 ? parts.join(" \xB7 ") : null;
+};
+var formatSectionDiagnosticStageWeightRows = (diagnostic) => (diagnostic.stageWeights ?? []).filter((entry) => entry.reasons.length > 0 || entry.stage === "rerank" || entry.stage === "finalize").map((entry) => {
+  const parts = [
+    `${formatSectionDiagnosticStage(entry.stage)} ${(entry.stageShare * 100).toFixed(0)}% of stage`,
+    typeof entry.stageScoreShare === "number" ? `${(entry.stageScoreShare * 100).toFixed(0)}% of stage score` : null,
+    typeof entry.retentionRate === "number" && entry.previousStage && entry.retentionRate !== 1 ? `${(entry.retentionRate * 100).toFixed(0)}% retained from ${formatSectionDiagnosticStage(entry.previousStage)}` : null,
+    typeof entry.countDelta === "number" && entry.countDelta !== 0 ? `delta ${entry.countDelta >= 0 ? "+" : ""}${entry.countDelta}` : null,
+    typeof entry.parentStageShare === "number" && entry.strongestSiblingLabel ? `${(entry.parentStageShare * 100).toFixed(0)}% of parent stage` : null,
+    typeof entry.parentStageScoreShare === "number" && entry.strongestSiblingLabel ? `${(entry.parentStageScoreShare * 100).toFixed(0)}% of parent stage score` : null,
+    typeof entry.stageShareGap === "number" ? `gap ${(entry.stageShareGap * 100).toFixed(0)}%` : null,
+    typeof entry.stageScoreShareGap === "number" ? `score gap ${(entry.stageScoreShareGap * 100).toFixed(0)}%` : null,
+    entry.strongestSiblingLabel ? `runner-up ${entry.strongestSiblingLabel}` : null
+  ].filter((value) => Boolean(value));
+  return parts.join(" \xB7 ");
+});
+var formatSectionDiagnosticStageWeightReasons = (diagnostic) => (diagnostic.stageWeights ?? []).flatMap((entry) => entry.reasons.map((reason) => `${formatSectionDiagnosticStage(entry.stage)} \xB7 ${formatSectionDiagnosticWeightReason(reason)}`));
+var formatSectionDiagnosticQueryAttributionReasons = (diagnostic) => (diagnostic.queryAttribution?.reasons ?? []).map((reason) => formatSectionQueryAttributionReason(reason));
+var formatSectionDiagnosticCompetition = (diagnostic) => {
+  const parts = [];
+  const parentShare = formatSectionDiagnosticPercent(diagnostic.parentShare);
+  const parentShareGap = formatSectionDiagnosticPercent(diagnostic.parentShareGap);
+  if (!diagnostic.strongestSiblingLabel)
+    return "";
+  if (parentShare)
+    parts.push(`parent share ${parentShare}`);
+  if (parentShareGap)
+    parts.push(`gap ${parentShareGap}`);
+  parts.push(`runner-up ${diagnostic.strongestSiblingLabel}`);
+  return parts.join(" \xB7 ");
+};
+var formatSectionDiagnosticTopEntry = (diagnostic) => {
+  const parts = [];
+  if (diagnostic.topSource)
+    parts.push(`top source ${diagnostic.topSource}`);
+  if (diagnostic.topChunkId)
+    parts.push(`lead chunk ${diagnostic.topChunkId}`);
+  parts.push(`${diagnostic.sourceCount} source${diagnostic.sourceCount === 1 ? "" : "s"}`);
+  parts.push(`primary ${diagnostic.queryAttribution?.primaryHits ?? 0} \xB7 transformed ${diagnostic.queryAttribution?.transformedHits ?? 0} \xB7 variant ${diagnostic.queryAttribution?.variantHits ?? 0}`);
+  return parts.join(" \xB7 ");
+};
+var formatSectionDiagnosticReasons = (diagnostic) => [
+  ...diagnostic.reasons.map((reason) => formatSectionDiagnosticReason(reason)),
+  ...formatSectionDiagnosticQueryAttributionReasons(diagnostic),
+  ...diagnostic.routingReason ? [`routing \xB7 ${diagnostic.routingReason}`] : [],
+  ...diagnostic.queryTransformReason ? [`transform \xB7 ${diagnostic.queryTransformReason}`] : []
+];
+var formatSectionDiagnosticDistributionRows = (diagnostic) => diagnostic.parentDistribution.map((entry) => `${entry.isActive ? "Active" : "Peer"} \xB7 ${entry.label} \xB7 ${entry.count} hit${entry.count === 1 ? "" : "s"} \xB7 ${formatSectionDiagnosticPercent(entry.parentShare) ?? "0%"}`);
+
 // src/presentation/htmxRenderers.ts
 var STREAM_STAGES = [
   "submitting",
@@ -11361,15 +11565,87 @@ var makeAdminActionCards = (prefix) => (actions) => {
       </article>`;
   }).join("")}</div>`;
 };
+var makeCitations = (prefix) => (sources) => {
+  const citations = buildRAGCitations(sources);
+  if (citations.length === 0) {
+    return "";
+  }
+  return [
+    `<div class="${prefix}-results">`,
+    "<h4>Citation Trail</h4>",
+    `<p class="${prefix}-metadata">Each citation maps a concrete retrieved chunk to a stable reference number you can carry into the answer UI.</p>`,
+    `<div class="${prefix}-result-grid">`,
+    buildCitationGroups(citations).map((group) => `
+          <article class="${prefix}-result-item" id="${escapeHtml(group.targetId)}">
+            <h3>${escapeHtml(group.label)}</h3>
+            <p class="${prefix}-result-source">${escapeHtml(group.summary)}</p>
+            <div class="${prefix}-result-grid">
+              ${group.citations.map((citation, index) => `
+                    <article class="${prefix}-result-item ${prefix}-citation-card">
+                      <p class="${prefix}-citation-badge">[${index + 1}] ${escapeHtml(formatCitationLabel(citation))}</p>
+                      <p class="${prefix}-result-score">${escapeHtml(formatCitationSummary(citation))}</p>
+                      ${formatCitationDetails(citation).map((line) => `<p class="${prefix}-metadata">${escapeHtml(line)}</p>`).join("")}
+                      <p class="${prefix}-result-text">${escapeHtml(formatCitationExcerpt(citation))}</p>
+                    </article>`).join("")}
+            </div>
+          </article>`).join(""),
+    "</div>",
+    "</div>"
+  ].join("");
+};
+var makeSourceSummaries = (prefix) => (sources) => {
+  const summaries = buildRAGSourceSummaries(sources);
+  if (summaries.length === 0) {
+    return `<p class="${prefix}-metadata">Retrieved source groups: 0</p>`;
+  }
+  const groups = buildSourceSummarySectionGroups(summaries);
+  return [
+    `<p class="${prefix}-metadata">Retrieved source groups: ${summaries.length}</p>`,
+    `<div class="${prefix}-result-grid">`,
+    groups.map((group) => `
+          <article class="${prefix}-result-item" id="${escapeHtml(group.targetId)}">
+            <h3>${escapeHtml(group.label)}</h3>
+            <p class="${prefix}-result-source">${escapeHtml(group.summary)}</p>
+            <div class="${prefix}-result-grid">
+              ${group.summaries.map((summary) => `
+                    <article class="${prefix}-result-item">
+                      <h4>${escapeHtml(summary.label)}</h4>
+                      ${formatSourceSummaryDetails(summary).map((line) => `<p class="${prefix}-metadata">${escapeHtml(line)}</p>`).join("")}
+                      <p class="${prefix}-result-text">${escapeHtml(summary.excerpt)}</p>
+                    </article>`).join("")}
+            </div>
+          </article>`).join(""),
+    "</div>"
+  ].join("");
+};
+var makeSectionDiagnosticCard = (prefix) => (diagnostic) => [
+  `<article class="${prefix}-result-item">`,
+  `<h4>${escapeHtml(diagnostic.label)}</h4>`,
+  `<p class="${prefix}-result-source">${escapeHtml(diagnostic.summary)}</p>`,
+  `<p class="${prefix}-metadata">${escapeHtml(formatSectionDiagnosticChannels(diagnostic))}</p>`,
+  `<p class="${prefix}-metadata">${escapeHtml(formatSectionDiagnosticAttributionFocus(diagnostic))}</p>`,
+  `<p class="${prefix}-metadata">${escapeHtml(formatSectionDiagnosticPipeline(diagnostic))}</p>`,
+  `${formatSectionDiagnosticStageFlow(diagnostic) ? `<p class="${prefix}-metadata">${escapeHtml(formatSectionDiagnosticStageFlow(diagnostic) ?? "")}</p>` : ""}`,
+  `${formatSectionDiagnosticStageBounds(diagnostic) ? `<p class="${prefix}-metadata">${escapeHtml(formatSectionDiagnosticStageBounds(diagnostic) ?? "")}</p>` : ""}`,
+  `${formatSectionDiagnosticStageWeightRows(diagnostic).map((line) => `<p class="${prefix}-metadata">${escapeHtml(line)}</p>`).join("")}`,
+  `<p class="${prefix}-metadata">${escapeHtml(formatSectionDiagnosticTopEntry(diagnostic))}</p>`,
+  `${formatSectionDiagnosticCompetition(diagnostic) ? `<p class="${prefix}-metadata">${escapeHtml(formatSectionDiagnosticCompetition(diagnostic) ?? "")}</p>` : ""}`,
+  `${[...formatSectionDiagnosticReasons(diagnostic), ...formatSectionDiagnosticStageWeightReasons(diagnostic)].length > 0 ? `<div class="${prefix}-badge-row">${[...formatSectionDiagnosticReasons(diagnostic), ...formatSectionDiagnosticStageWeightReasons(diagnostic)].map((reason) => `<span class="${prefix}-state-chip">${escapeHtml(reason)}</span>`).join("")}</div>` : ""}`,
+  `${formatSectionDiagnosticDistributionRows(diagnostic).map((line) => `<p class="${prefix}-metadata">${escapeHtml(line)}</p>`).join("")}`,
+  `</article>`
+].join("");
 var resolveRAGHTMXRenderers = (custom = {}) => {
   const classPrefix = custom.classPrefix ?? "rag";
   return {
     adminActionCards: custom.adminActionCards ?? makeAdminActionCards(classPrefix),
     adminJobCards: custom.adminJobCards ?? makeAdminJobCards(classPrefix),
     capabilities: custom.capabilities ?? makeCapabilities(classPrefix),
+    citations: custom.citations ?? makeCitations(classPrefix),
     classPrefix,
     detailList: custom.detailList ?? makeDetailList(classPrefix),
     nativeSource: custom.nativeSource ?? defaultNativeSource,
+    sectionDiagnosticCard: custom.sectionDiagnosticCard ?? makeSectionDiagnosticCard(classPrefix),
+    sourceSummaries: custom.sourceSummaries ?? makeSourceSummaries(classPrefix),
     stageRow: custom.stageRow ?? makeStageRow(classPrefix),
     statusMessage: custom.statusMessage ?? defaultStatusMessage,
     statusSummary: custom.statusSummary ?? defaultStatusSummary,
@@ -11381,6 +11657,24 @@ export {
   resolveRAGHTMXRenderers,
   getLatestRAGSources,
   getLatestAssistantMessage,
+  formatSourceSummaryDetails,
+  formatSectionDiagnosticTopEntry,
+  formatSectionDiagnosticStageWeightRows,
+  formatSectionDiagnosticStageWeightReasons,
+  formatSectionDiagnosticStageFlow,
+  formatSectionDiagnosticStageBounds,
+  formatSectionDiagnosticReasons,
+  formatSectionDiagnosticPipeline,
+  formatSectionDiagnosticDistributionRows,
+  formatSectionDiagnosticCompetition,
+  formatSectionDiagnosticChannels,
+  formatSectionDiagnosticAttributionFocus,
+  formatCitationSummary,
+  formatCitationLabel,
+  formatCitationExcerpt,
+  formatCitationDetails,
+  buildSourceSummarySectionGroups,
+  buildSearchTargetId,
   buildRAGSyncSourcePresentations,
   buildRAGSyncSourcePresentation,
   buildRAGSyncOverviewPresentation,
@@ -11431,8 +11725,10 @@ export {
   buildRAGAdminJobPresentations,
   buildRAGAdminJobPresentation,
   buildRAGAdminActionPresentations,
-  buildRAGAdminActionPresentation
+  buildRAGAdminActionPresentation,
+  buildGroundingReferenceGroups,
+  buildCitationGroups
 };
 
-//# debugId=B8E44E48C030946D64756E2164756E21
+//# debugId=FCAE71C0401EF18B64756E2164756E21
 //# sourceMappingURL=ui.js.map