@absolutejs/absolute 0.19.0-beta.609 → 0.19.0-beta.610

package/dist/ai-client/react/ai/index.js

@@ -831,21 +831,48 @@ var buildExcerpt = (text, maxLength = 160) => {
 };
 var selectPreferredExcerpt = (excerpts, sectionChunkCount) => {
   if (!excerpts) {
-    return "";
+    return {
+      excerpt: "",
+      mode: "chunk",
+      reason: "single_chunk"
+    };
   }
   const chunkExcerpt = excerpts.chunkExcerpt?.trim() ?? "";
   const windowExcerpt = excerpts.windowExcerpt?.trim() ?? "";
   const sectionExcerpt = excerpts.sectionExcerpt?.trim() ?? "";
   if (sectionChunkCount && sectionChunkCount > 1 && chunkExcerpt.length > 0 && chunkExcerpt.length < 72) {
     if (sectionChunkCount <= 3 && sectionExcerpt) {
-      return sectionExcerpt;
+      return {
+        excerpt: sectionExcerpt,
+        mode: "section",
+        reason: "section_small_enough"
+      };
     }
     if (windowExcerpt) {
-      return windowExcerpt;
+      return {
+        excerpt: windowExcerpt,
+        mode: "window",
+        reason: "section_too_large_use_window"
+      };
     }
+    return {
+      excerpt: chunkExcerpt,
+      mode: "chunk",
+      reason: "chunk_too_narrow"
+    };
   }
-  return chunkExcerpt || windowExcerpt || sectionExcerpt;
+  return {
+    excerpt: chunkExcerpt || windowExcerpt || sectionExcerpt,
+    mode: "chunk",
+    reason: (sectionChunkCount ?? 0) > 1 ? "chunk_too_narrow" : "single_chunk"
+  };
 };
+var buildExcerptModeCounts = (references) => references.reduce((counts, reference) => {
+  if (reference?.excerptSelection) {
+    counts[reference.excerptSelection.mode] += 1;
+  }
+  return counts;
+}, { chunk: 0, section: 0, window: 0 });
 var buildGroundingChunkExcerpts = (sources, activeChunkId) => {
   if (sources.length === 0) {
     return;
@@ -901,8 +928,9 @@ var buildGroundedAnswerCitationDetail = (reference) => ({
   contextLabel: reference.contextLabel,
   evidenceLabel: buildGroundingReferenceEvidenceLabel(reference),
   evidenceSummary: buildGroundingReferenceEvidenceSummary(reference),
-  excerpt: selectPreferredExcerpt(reference.excerpts, getContextNumber(reference.metadata?.sectionChunkCount)) || reference.excerpt,
+  excerpt: selectPreferredExcerpt(reference.excerpts, getContextNumber(reference.metadata?.sectionChunkCount)).excerpt || reference.excerpt,
   excerpts: reference.excerpts,
+  excerptSelection: reference.excerptSelection,
   label: reference.label,
   locatorLabel: reference.locatorLabel,
   number: reference.number,
@@ -919,11 +947,14 @@ var buildRAGCitations = (sources) => {
     const hasBetterExisting = existing !== undefined && existing.score >= source.score;
     if (hasBetterExisting)
       continue;
+    const excerpts = buildGroundingChunkExcerpts(sources, source.chunkId);
+    const excerptSelection = selectPreferredExcerpt(excerpts, getContextNumber(source.metadata?.sectionChunkCount));
     unique.set(key, {
       chunkId: source.chunkId,
       contextLabel: source.labels?.contextLabel ?? buildContextLabel(source.metadata),
-      excerpt: selectPreferredExcerpt(buildGroundingChunkExcerpts(sources, source.chunkId), getContextNumber(source.metadata?.sectionChunkCount)) || buildExcerpt(source.text),
-      excerpts: buildGroundingChunkExcerpts(sources, source.chunkId),
+      excerpt: excerptSelection.excerpt || buildExcerpt(source.text),
+      excerpts,
+      excerptSelection,
       key,
       label: buildSourceLabel(source),
       locatorLabel: source.labels?.locatorLabel ?? buildLocatorLabel(source.metadata, source.source, source.title),
@@ -944,6 +975,7 @@ var buildRAGCitations = (sources) => {
 };
 var buildRAGGroundedAnswer = (content, sources) => {
   const references = buildRAGGroundingReferences(sources);
+  const sectionSummaries = buildRAGGroundedAnswerSectionSummaries(references);
   const referenceMap = new Map(references.map((reference) => [reference.number, reference]));
   const parts = [];
   const ungroundedReferenceNumbers = new Set;
@@ -987,10 +1019,14 @@ var buildRAGGroundedAnswer = (content, sources) => {
   return {
     content,
     coverage,
+    excerptModeCounts: buildExcerptModeCounts([
+      ...references,
+      ...sectionSummaries
+    ]),
     hasCitations,
     parts,
     references,
-    sectionSummaries: buildRAGGroundedAnswerSectionSummaries(references),
+    sectionSummaries,
     ungroundedReferenceNumbers: [...ungroundedReferenceNumbers].sort((left, right) => left - right)
   };
 };
@@ -1009,8 +1045,9 @@ var buildRAGGroundedAnswerSectionSummaries = (references) => {
         chunkIds: [reference.chunkId],
         contextLabel: reference.contextLabel,
         count: 1,
-        excerpt: selectPreferredExcerpt(excerpts, getContextNumber(reference.metadata?.sectionChunkCount)) || excerpts?.sectionExcerpt || reference.excerpt,
+        excerpt: selectPreferredExcerpt(excerpts, getContextNumber(reference.metadata?.sectionChunkCount)).excerpt || excerpts?.sectionExcerpt || reference.excerpt,
         excerpts,
+        excerptSelection: reference.excerptSelection,
         key,
         label: key,
         locatorLabel: reference.locatorLabel,
@@ -1046,6 +1083,9 @@ var buildRAGGroundedAnswerSectionSummaries = (references) => {
       };
       existing.excerpt = reference.excerpts.sectionExcerpt;
     }
+    if (!existing.excerptSelection && reference.excerptSelection) {
+      existing.excerptSelection = reference.excerptSelection;
+    }
   }
   return [...groups.values()].map((group) => ({
     ...group,
@@ -1065,11 +1105,13 @@ var buildRAGGroundingReferences = (sources) => {
   const citationReferenceMap = buildRAGCitationReferenceMap(citations);
   return citations.map((citation) => {
     const excerpts = buildGroundingChunkExcerpts(sources, citation.chunkId);
+    const excerptSelection = selectPreferredExcerpt(excerpts, getContextNumber(citation.metadata?.sectionChunkCount));
     return {
       chunkId: citation.chunkId,
       contextLabel: citation.contextLabel ?? buildContextLabel(citation.metadata),
-      excerpt: selectPreferredExcerpt(excerpts, getContextNumber(citation.metadata?.sectionChunkCount)) || excerpts?.chunkExcerpt || buildExcerpt(citation.text),
+      excerpt: excerptSelection.excerpt || excerpts?.chunkExcerpt || buildExcerpt(citation.text),
       excerpts,
+      excerptSelection,
       label: citation.label,
       locatorLabel: citation.locatorLabel ?? buildLocatorLabel(citation.metadata, citation.source, citation.title),
       metadata: citation.metadata,
@@ -1323,22 +1365,49 @@ var buildRAGChunkExcerpts = (chunks, activeChunkId) => {
     windowExcerpt: buildExcerpt2(collectText(orderedWindowIds), 240)
   };
 };
-var buildRAGPreferredExcerpt = (excerpts, structure) => {
+var buildRAGExcerptSelection = (excerpts, structure) => {
   if (!excerpts) {
-    return "";
+    return {
+      excerpt: "",
+      mode: "chunk",
+      reason: "single_chunk"
+    };
   }
   const chunkLength = excerpts.chunkExcerpt.trim().length;
   const sectionChunkCount = structure?.sequence?.sectionChunkCount ?? 1;
   if (sectionChunkCount > 1 && chunkLength > 0 && chunkLength < 72) {
     if (sectionChunkCount <= 3 && excerpts.sectionExcerpt.trim().length > 0) {
-      return excerpts.sectionExcerpt;
+      return {
+        excerpt: excerpts.sectionExcerpt,
+        mode: "section",
+        reason: "section_small_enough"
+      };
     }
     if (excerpts.windowExcerpt.trim().length > 0) {
-      return excerpts.windowExcerpt;
+      return {
+        excerpt: excerpts.windowExcerpt,
+        mode: "window",
+        reason: "section_too_large_use_window"
+      };
     }
+    return {
+      excerpt: excerpts.chunkExcerpt,
+      mode: "chunk",
+      reason: "chunk_too_narrow"
+    };
   }
-  return excerpts.chunkExcerpt;
+  return {
+    excerpt: excerpts.chunkExcerpt,
+    mode: "chunk",
+    reason: sectionChunkCount > 1 ? "chunk_too_narrow" : "single_chunk"
+  };
 };
+var buildRAGExcerptModeCounts = (selections) => selections.reduce((counts, selection) => {
+  if (selection) {
+    counts[selection.mode] += 1;
+  }
+  return counts;
+}, { chunk: 0, section: 0, window: 0 });
 var buildRAGChunkGraph = (chunks) => {
   const nodes = [];
   const edges = [];
@@ -1527,19 +1596,27 @@ var buildRAGRetrievedState = (messages) => {
     return null;
   }
   const sources = message.sources ?? [];
+  const citations = buildRAGCitations(sources);
+  const sectionDiagnostics = buildRAGSectionRetrievalDiagnostics(sources, isRAGRetrievalTrace(message.retrievalTrace) ? message.retrievalTrace : undefined);
+  const sourceSummaries = buildRAGSourceSummaries(sources);
   const groundedAnswer = buildRAGGroundedAnswer(message.content, sources);
   return {
-    citationReferenceMap: buildRAGCitationReferenceMap(buildRAGCitations(sources)),
-    citations: buildRAGCitations(sources),
+    citationReferenceMap: buildRAGCitationReferenceMap(citations),
+    citations,
     conversationId: message.conversationId,
+    excerptModeCounts: buildRAGExcerptModeCounts([
+      ...citations.map((citation) => citation.excerptSelection),
+      ...sourceSummaries.map((summary) => summary.excerptSelection)
+    ]),
     groundedAnswer,
     messageId: message.id,
     retrievalDurationMs: message.retrievalDurationMs,
     retrievalStartedAt: message.retrievalStartedAt,
     retrievedAt: message.retrievedAt,
     trace: isRAGRetrievalTrace(message.retrievalTrace) ? message.retrievalTrace : undefined,
+    sectionDiagnostics,
     sourceGroups: buildRAGSourceGroups(sources),
-    sourceSummaries: buildRAGSourceSummaries(sources),
+    sourceSummaries,
     sources
   };
 };
@@ -1551,6 +1628,8 @@ var buildRAGSourceSummaries = (sources) => {
     const groupCitations = citations.filter((citation) => group.chunks.some((chunk) => chunk.chunkId === citation.chunkId));
     const leadChunk = group.chunks.slice().sort((left, right) => right.score - left.score)[0];
     const excerpts = leadChunk ? buildRAGChunkExcerpts(group.chunks, leadChunk.chunkId) : undefined;
+    const structure = leadChunk?.structure ?? buildRAGChunkStructure(leadChunk?.metadata);
+    const excerptSelection = buildRAGExcerptSelection(excerpts, structure);
     return {
       bestScore: group.bestScore,
       citationNumbers: groupCitations.map((citation) => citationReferenceMap[citation.chunkId] ?? 0),
@@ -1558,18 +1637,154 @@ var buildRAGSourceSummaries = (sources) => {
       chunkIds: group.chunks.map((chunk) => chunk.chunkId),
       contextLabel: leadChunk?.labels?.contextLabel ?? buildContextLabel2(leadChunk?.metadata),
       count: group.count,
-      excerpt: buildRAGPreferredExcerpt(excerpts, leadChunk?.structure ?? buildRAGChunkStructure(leadChunk?.metadata)) || buildExcerpt2(leadChunk?.text ?? ""),
+      excerpt: excerptSelection.excerpt || buildExcerpt2(leadChunk?.text ?? ""),
       excerpts,
+      excerptSelection,
       key: group.key,
       label: group.label,
       locatorLabel: leadChunk?.labels?.locatorLabel ?? buildLocatorLabel2(leadChunk?.metadata, leadChunk?.source, leadChunk?.title),
       provenanceLabel: leadChunk?.labels?.provenanceLabel ?? buildProvenanceLabel2(leadChunk?.metadata),
-      structure: leadChunk?.structure ?? buildRAGChunkStructure(leadChunk?.metadata),
+      structure,
       source: group.source,
       title: group.title
     };
   });
 };
+var getSectionPathFromSource = (source) => {
+  const path = source.structure?.section?.path ?? (Array.isArray(source.metadata?.sectionPath) ? source.metadata.sectionPath.map((value) => getContextString2(value)).filter((value) => typeof value === "string") : []);
+  return path.length > 0 ? path : undefined;
+};
+var buildRAGSectionRetrievalDiagnostics = (sources, trace) => {
+  const totalScore = sources.reduce((sum, source) => sum + source.score, 0);
+  if (sources.length === 0 || totalScore <= 0) {
+    return [];
+  }
+  const sections = new Map;
+  for (const source of sources) {
+    const path = getSectionPathFromSource(source);
+    if (!path) {
+      continue;
+    }
+    const key = path.join(" > ");
+    const label = path.at(-1) ?? key;
+    const parentLabel = path.length > 1 ? path.slice(0, -1).join(" > ") : undefined;
+    const existing = sections.get(key);
+    const channels = Array.isArray(source.metadata?.retrievalChannels) ? source.metadata.retrievalChannels.filter((value) => value === "vector" || value === "lexical") : [];
+    const isHybrid = channels.includes("vector") && channels.includes("lexical");
+    const vectorHits = channels.includes("vector") ? 1 : 0;
+    const lexicalHits = channels.includes("lexical") ? 1 : 0;
+    const hybridHits = isHybrid ? 1 : 0;
+    if (!existing) {
+      sections.set(key, {
+        bestScore: source.score,
+        count: 1,
+        hybridHits,
+        key,
+        label,
+        lexicalHits,
+        parentLabel,
+        path,
+        sourceSet: new Set(source.source ? [source.source] : []),
+        topChunkId: source.chunkId,
+        topSource: source.source,
+        totalScore: source.score,
+        vectorHits
+      });
+      continue;
+    }
+    existing.count += 1;
+    existing.totalScore += source.score;
+    if (source.source) {
+      existing.sourceSet.add(source.source);
+    }
+    existing.vectorHits += vectorHits;
+    existing.lexicalHits += lexicalHits;
+    existing.hybridHits += hybridHits;
+    if (source.score > existing.bestScore) {
+      existing.bestScore = source.score;
+      existing.topChunkId = source.chunkId;
+      existing.topSource = source.source;
+    }
+  }
+  const diagnostics = [...sections.values()];
+  const strongestBestHit = diagnostics.reduce((highest, section) => Math.max(highest, section.bestScore), 0);
+  return diagnostics.map((section) => {
+    const siblingPool = diagnostics.filter((entry) => entry.parentLabel === section.parentLabel);
+    const siblings = siblingPool.filter((entry) => entry.key !== section.key);
+    const strongestSibling = siblings.slice().sort((left, right) => right.totalScore - left.totalScore)[0];
+    const parentTotal = siblingPool.reduce((sum, entry) => sum + entry.totalScore, 0);
+    const scoreShare = section.totalScore / totalScore;
+    const parentShare = parentTotal > 0 ? section.totalScore / parentTotal : undefined;
+    const parentDistribution = parentTotal > 0 ? siblingPool.map((entry) => ({
+      count: entry.count,
+      isActive: entry.key === section.key,
+      key: entry.key,
+      label: entry.label,
+      parentShare: entry.totalScore / parentTotal,
+      totalScore: entry.totalScore
+    })).sort((left, right) => right.totalScore - left.totalScore) : [];
+    const reasons = [];
+    if (section.bestScore >= strongestBestHit) {
+      reasons.push("best_hit");
+    }
+    if (section.count > 1) {
+      reasons.push("multi_hit_section");
+    }
+    if (siblings.length === 0) {
+      reasons.push("only_section_in_parent");
+    } else if (!strongestSibling || section.totalScore >= strongestSibling.totalScore) {
+      reasons.push("dominant_within_parent");
+    }
+    if (scoreShare >= 0.5 || (parentShare ?? 0) >= 0.6) {
+      reasons.push("concentrated_evidence");
+    }
+    const summaryParts = [
+      `${section.count} hit${section.count === 1 ? "" : "s"}`,
+      `${(scoreShare * 100).toFixed(0)}% score share`,
+      `vector ${section.vectorHits} · lexical ${section.lexicalHits} · hybrid ${section.hybridHits}`,
+      typeof parentShare === "number" ? `${(parentShare * 100).toFixed(0)}% of parent section set` : "",
+      strongestSibling ? `ahead of ${strongestSibling.label} by ${(section.totalScore - strongestSibling.totalScore).toFixed(2)}` : "no sibling competition"
+    ].filter(Boolean);
+    return {
+      averageScore: section.totalScore / section.count,
+      bestScore: section.bestScore,
+      count: section.count,
+      key: section.key,
+      label: section.label,
+      parentLabel: section.parentLabel,
+      parentDistribution,
+      parentShare,
+      parentShareGap: typeof parentShare === "number" && strongestSibling && parentTotal > 0 ? parentShare - strongestSibling.totalScore / parentTotal : undefined,
+      path: section.path,
+      retrievalMode: trace?.mode,
+      reasons,
+      rerankApplied: trace?.steps.some((step) => step.stage === "rerank" && step.metadata?.applied === true),
+      scoreShare,
+      scoreThresholdApplied: trace?.steps.some((step) => step.stage === "score_filter"),
+      siblingCount: siblings.length,
+      siblingScoreGap: strongestSibling ? section.totalScore - strongestSibling.totalScore : undefined,
+      sourceCount: section.sourceSet.size,
+      sourceBalanceApplied: trace?.steps.some((step) => step.stage === "source_balance"),
+      strongestSiblingLabel: strongestSibling?.label,
+      strongestSiblingScore: strongestSibling?.totalScore,
+      summary: summaryParts.join(" · "),
+      topChunkId: section.topChunkId,
+      topSource: section.topSource,
+      totalScore: section.totalScore,
+      hybridHits: section.hybridHits,
+      lexicalHits: section.lexicalHits,
+      vectorHits: section.vectorHits
+    };
+  }).sort((left, right) => {
+    if (right.totalScore !== left.totalScore) {
+      return right.totalScore - left.totalScore;
+    }
+    if (right.bestScore !== left.bestScore) {
+      return right.bestScore - left.bestScore;
+    }
+    return left.label.localeCompare(right.label);
+  });
+};
 var buildStreamProgressState = (messages) => {
   const latestMessage = getLatestAssistantMessage(messages);
   const retrieved = latestMessage ? buildRAGRetrievedState(messages) : undefined;
@@ -1633,12 +1848,19 @@ var buildRAGAnswerWorkflowState = ({
   const groundingReferences = buildRAGGroundingReferences(sources);
   const groundedAnswer = buildRAGGroundedAnswer(latestAssistantMessage?.content ?? "", sources);
   const retrieval = buildRAGRetrievedState(messages);
+  const sectionDiagnostics = buildRAGSectionRetrievalDiagnostics(sources, retrieval?.trace);
   const progress = buildRAGStreamProgress({
     error,
     isStreaming,
     messages
   });
   return {
+    excerptModeCounts: buildRAGExcerptModeCounts([
+      ...citations.map((citation) => citation.excerptSelection),
+      ...sourceSummaries.map((summary) => summary.excerptSelection),
+      ...groundingReferences.map((reference) => reference.excerptSelection),
+      ...groundedAnswer.sectionSummaries.map((summary) => summary.excerptSelection)
+    ]),
     citationReferenceMap,
     citations,
     coverage: groundedAnswer.coverage,
@@ -1663,6 +1885,7 @@ var buildRAGAnswerWorkflowState = ({
     retrievalDurationMs: retrieval?.retrievalDurationMs,
     retrievalStartedAt: retrieval?.retrievalStartedAt,
     retrievedAt: retrieval?.retrievedAt,
+    sectionDiagnostics,
     sourceGroups,
     sourceSummaries,
     sources,
@@ -3251,6 +3474,21 @@ var useRAGChunkPreview = (path) => {
   }, []);
   const chunkGraph = useMemo(() => preview ? buildRAGChunkPreviewGraph(preview) : null, [preview]);
   const navigation = useMemo(() => preview ? buildRAGChunkPreviewNavigation(preview, activeChunkId ?? undefined) : null, [activeChunkId, preview]);
+  const previewSources = useMemo(() => preview ? preview.chunks.map((chunk, index) => ({
+    chunkId: chunk.chunkId,
+    labels: chunk.labels,
+    metadata: chunk.metadata,
+    score: Math.max(0, preview.chunks.length - index),
+    source: chunk.source ?? preview.document.source,
+    structure: chunk.structure,
+    text: chunk.text,
+    title: chunk.title ?? preview.document.title
+  })) : [], [preview]);
+  const sectionDiagnostics = useMemo(() => buildRAGSectionRetrievalDiagnostics(previewSources), [previewSources]);
+  const activeSectionDiagnostic = useMemo(() => {
+    const sectionKey = navigation?.section?.path?.join(" > ");
+    return sectionKey ? sectionDiagnostics.find((diagnostic) => diagnostic.key === sectionKey) ?? null : null;
+  }, [navigation, sectionDiagnostics]);
   const selectChunk = useCallback2((id) => {
     setActiveChunkId(id);
   }, []);
@@ -3274,6 +3512,7 @@ var useRAGChunkPreview = (path) => {
   }, [navigation]);
   return {
     activeChunkId,
+    activeSectionDiagnostic,
     chunkGraph,
     clear,
     error,
@@ -3281,6 +3520,7 @@ var useRAGChunkPreview = (path) => {
     isLoading,
     navigation,
     preview,
+    sectionDiagnostics,
     selectChildSection,
     selectChunk,
     selectParentSection,
@@ -3865,6 +4105,7 @@ var useRAGSources = (messages) => {
   const sources = useMemo10(() => getLatestRAGSources(messages), [messages]);
   const sourceGroups = useMemo10(() => buildRAGSourceGroups(sources), [sources]);
   const sourceSummaries = useMemo10(() => buildRAGSourceSummaries(sources), [sources]);
+  const sectionDiagnostics = useMemo10(() => buildRAGSectionRetrievalDiagnostics(sources, latestAssistantMessage?.retrievalTrace), [sources, latestAssistantMessage]);
   const chunkGraph = useMemo10(() => buildRAGChunkGraph(sources), [sources]);
   const citationReferenceMap = useMemo10(() => buildRAGCitationReferenceMap(sourceSummaries.flatMap((summary) => summary.citations)), [sourceSummaries]);
   const navigationForChunk = useCallback9((chunkId) => buildRAGChunkGraphNavigation(chunkGraph, chunkId ?? undefined), [chunkGraph]);
@@ -3874,6 +4115,7 @@ var useRAGSources = (messages) => {
     hasSources: sources.length > 0,
     latestAssistantMessage,
     navigationForChunk,
+    sectionDiagnostics,
     sourceGroups,
     sources,
     sourceSummaries