@absolutejs/absolute 0.19.0-beta.603 → 0.19.0-beta.605

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

@@ -698,6 +698,10 @@ var buildContextLabel = (metadata) => {
     return from ? `Message from ${from}` : "Message evidence";
   }
   const page = getContextNumber(metadata.page) ?? getContextNumber(metadata.pageNumber) ?? (typeof metadata.pageIndex === "number" ? metadata.pageIndex + 1 : undefined);
+  const region = getContextNumber(metadata.regionNumber) ?? (typeof metadata.regionIndex === "number" ? metadata.regionIndex + 1 : undefined);
+  if (page && region) {
+    return `Page ${page} region ${region}`;
+  }
   if (page) {
     return `Page ${page}`;
   }
@@ -721,6 +725,11 @@ var buildContextLabel = (metadata) => {
   if (speaker) {
     return `Speaker ${speaker}`;
   }
+  const sectionPath = Array.isArray(metadata.sectionPath) ? metadata.sectionPath.map((value) => getContextString(value)).filter((value) => typeof value === "string") : [];
+  const sectionTitle = getContextString(metadata.sectionTitle) ?? sectionPath.at(-1);
+  if (sectionTitle) {
+    return `Section ${sectionTitle}`;
+  }
   return;
 };
 var formatMediaTimestamp = (value) => {
@@ -738,6 +747,10 @@ var buildLocatorLabel = (metadata, source, title) => {
     return;
   }
   const page = getContextNumber(metadata.page) ?? getContextNumber(metadata.pageNumber) ?? (typeof metadata.pageIndex === "number" ? metadata.pageIndex + 1 : undefined);
+  const region = getContextNumber(metadata.regionNumber) ?? (typeof metadata.regionIndex === "number" ? metadata.regionIndex + 1 : undefined);
+  if (page && region) {
+    return `Page ${page} · Region ${region}`;
+  }
   if (page) {
     return `Page ${page}`;
   }
@@ -766,6 +779,10 @@ var buildLocatorLabel = (metadata, source, title) => {
   if (mediaStart) {
     return `Timestamp ${mediaStart}`;
   }
+  const sectionPath = Array.isArray(metadata.sectionPath) ? metadata.sectionPath.map((value) => getContextString(value)).filter((value) => typeof value === "string") : [];
+  if (sectionPath.length > 0) {
+    return `Section ${sectionPath.join(" > ")}`;
+  }
   return;
 };
 var formatTimestampLabel = (value) => {
@@ -790,9 +807,11 @@ var buildProvenanceLabel = (metadata) => {
   const transcriptSource = getContextString(metadata.transcriptSource);
   const pdfTextMode = getContextString(metadata.pdfTextMode);
   const ocrEngine = getContextString(metadata.ocrEngine);
+  const ocrConfidence = getContextNumber(metadata.ocrRegionConfidence) ?? getContextNumber(metadata.ocrConfidence);
   const labels = [
     pdfTextMode ? `PDF ${pdfTextMode}` : "",
     ocrEngine ? `OCR ${ocrEngine}` : "",
+    typeof ocrConfidence === "number" ? `Confidence ${ocrConfidence.toFixed(2)}` : "",
     mediaKind ? `Media ${mediaKind}` : "",
     transcriptSource ? `Transcript ${transcriptSource}` : "",
     threadTopic ? `Thread ${threadTopic}` : "",
@@ -813,8 +832,10 @@ var buildExcerpt = (text, maxLength = 160) => {
 var buildGroundingReferenceEvidenceLabel = (reference) => [reference.label, reference.locatorLabel, reference.contextLabel].filter((value) => Boolean(value && value.length > 0)).filter((value, index, values) => values.findIndex((entry) => entry === value) === index).join(" · ");
 var buildGroundingReferenceEvidenceSummary = (reference) => [
   reference.source ?? reference.title ?? reference.chunkId,
+  reference.locatorLabel,
+  reference.contextLabel,
   reference.provenanceLabel
-].filter((value) => Boolean(value && value.length > 0)).join(" · ");
+].filter((value) => Boolean(value && value.length > 0)).filter((value, index, values) => values.findIndex((entry) => entry === value) === index).join(" · ");
 var buildGroundedAnswerCitationDetail = (reference) => ({
   contextLabel: reference.contextLabel,
   evidenceLabel: buildGroundingReferenceEvidenceLabel(reference),
@@ -838,12 +859,12 @@ var buildRAGCitations = (sources) => {
       continue;
     unique.set(key, {
       chunkId: source.chunkId,
-      contextLabel: buildContextLabel(source.metadata),
+      contextLabel: source.labels?.contextLabel ?? buildContextLabel(source.metadata),
       key,
       label: buildSourceLabel(source),
-      locatorLabel: buildLocatorLabel(source.metadata, source.source, source.title),
+      locatorLabel: source.labels?.locatorLabel ?? buildLocatorLabel(source.metadata, source.source, source.title),
       metadata: source.metadata,
-      provenanceLabel: buildProvenanceLabel(source.metadata),
+      provenanceLabel: source.labels?.provenanceLabel ?? buildProvenanceLabel(source.metadata),
       score: source.score,
       source: source.source,
       text: source.text,
@@ -913,7 +934,7 @@ var buildRAGGroundingReferences = (sources) => {
   const citationReferenceMap = buildRAGCitationReferenceMap(citations);
   return citations.map((citation) => ({
     chunkId: citation.chunkId,
-    contextLabel: buildContextLabel(citation.metadata),
+    contextLabel: citation.contextLabel ?? buildContextLabel(citation.metadata),
     excerpt: buildExcerpt(citation.text),
     label: citation.label,
     locatorLabel: citation.locatorLabel ?? buildLocatorLabel(citation.metadata, citation.source, citation.title),
@@ -983,6 +1004,10 @@ var buildContextLabel2 = (metadata) => {
     return from ? `Message from ${from}` : "Message evidence";
   }
   const page = getContextNumber2(metadata.page) ?? getContextNumber2(metadata.pageNumber) ?? (typeof metadata.pageIndex === "number" ? metadata.pageIndex + 1 : undefined);
+  const region = getContextNumber2(metadata.regionNumber) ?? (typeof metadata.regionIndex === "number" ? metadata.regionIndex + 1 : undefined);
+  if (page && region) {
+    return `Page ${page} region ${region}`;
+  }
   if (page) {
     return `Page ${page}`;
   }
@@ -1006,6 +1031,11 @@ var buildContextLabel2 = (metadata) => {
   if (speaker) {
     return `Speaker ${speaker}`;
   }
+  const sectionPath = Array.isArray(metadata.sectionPath) ? metadata.sectionPath.map((value) => getContextString2(value)).filter((value) => typeof value === "string") : [];
+  const sectionTitle = getContextString2(metadata.sectionTitle) ?? sectionPath.at(-1);
+  if (sectionTitle) {
+    return `Section ${sectionTitle}`;
+  }
   return;
 };
 var buildLocatorLabel2 = (metadata, source, title) => {
@@ -1013,6 +1043,10 @@ var buildLocatorLabel2 = (metadata, source, title) => {
     return;
   }
   const page = getContextNumber2(metadata.page) ?? getContextNumber2(metadata.pageNumber) ?? (typeof metadata.pageIndex === "number" ? metadata.pageIndex + 1 : undefined);
+  const region = getContextNumber2(metadata.regionNumber) ?? (typeof metadata.regionIndex === "number" ? metadata.regionIndex + 1 : undefined);
+  if (page && region) {
+    return `Page ${page} · Region ${region}`;
+  }
   if (page) {
     return `Page ${page}`;
   }
@@ -1041,6 +1075,10 @@ var buildLocatorLabel2 = (metadata, source, title) => {
   if (mediaStart) {
     return `Timestamp ${mediaStart}`;
   }
+  const sectionPath = Array.isArray(metadata.sectionPath) ? metadata.sectionPath.map((value) => getContextString2(value)).filter((value) => typeof value === "string") : [];
+  if (sectionPath.length > 0) {
+    return `Section ${sectionPath.join(" > ")}`;
+  }
   return;
 };
 var buildProvenanceLabel2 = (metadata) => {
@@ -1055,9 +1093,11 @@ var buildProvenanceLabel2 = (metadata) => {
   const transcriptSource = getContextString2(metadata.transcriptSource);
   const pdfTextMode = getContextString2(metadata.pdfTextMode);
   const ocrEngine = getContextString2(metadata.ocrEngine);
+  const ocrConfidence = getContextNumber2(metadata.ocrRegionConfidence) ?? getContextNumber2(metadata.ocrConfidence);
   const labels = [
     pdfTextMode ? `PDF ${pdfTextMode}` : "",
     ocrEngine ? `OCR ${ocrEngine}` : "",
+    typeof ocrConfidence === "number" ? `Confidence ${ocrConfidence.toFixed(2)}` : "",
     mediaKind ? `Media ${mediaKind}` : "",
     transcriptSource ? `Transcript ${transcriptSource}` : "",
     threadTopic ? `Thread ${threadTopic}` : "",
@@ -1067,6 +1107,50 @@ var buildProvenanceLabel2 = (metadata) => {
   ].filter((value) => value.length > 0);
   return labels.length > 0 ? labels.join(" · ") : undefined;
 };
+var buildRAGSourceLabels = ({
+  metadata,
+  source,
+  title
+}) => {
+  const contextLabel = buildContextLabel2(metadata);
+  const locatorLabel = buildLocatorLabel2(metadata, source, title);
+  const provenanceLabel = buildProvenanceLabel2(metadata);
+  if (!contextLabel && !locatorLabel && !provenanceLabel) {
+    return;
+  }
+  return {
+    contextLabel,
+    locatorLabel,
+    provenanceLabel
+  };
+};
+var buildRAGChunkStructure = (metadata) => {
+  if (!metadata) {
+    return;
+  }
+  const sectionPath = Array.isArray(metadata.sectionPath) ? metadata.sectionPath.filter((value) => typeof value === "string" && value.trim().length > 0) : undefined;
+  const sectionKind = metadata.sectionKind === "markdown_heading" || metadata.sectionKind === "html_heading" ? metadata.sectionKind : undefined;
+  const section = {
+    depth: getContextNumber2(metadata.sectionDepth),
+    kind: sectionKind,
+    path: sectionPath && sectionPath.length > 0 ? sectionPath : undefined,
+    title: getContextString2(metadata.sectionTitle)
+  };
+  const sequence = {
+    nextChunkId: getContextString2(metadata.nextChunkId),
+    previousChunkId: getContextString2(metadata.previousChunkId),
+    sectionChunkCount: getContextNumber2(metadata.sectionChunkCount),
+    sectionChunkId: getContextString2(metadata.sectionChunkId),
+    sectionChunkIndex: getContextNumber2(metadata.sectionChunkIndex)
+  };
+  if (!section.title && (!section.path || section.path.length === 0) && typeof section.depth !== "number" && !section.kind && !sequence.nextChunkId && !sequence.previousChunkId && typeof sequence.sectionChunkCount !== "number" && !sequence.sectionChunkId && typeof sequence.sectionChunkIndex !== "number") {
+    return;
+  }
+  return {
+    section: section.title || section.path && section.path.length > 0 || typeof section.depth === "number" || section.kind ? section : undefined,
+    sequence: sequence.nextChunkId || sequence.previousChunkId || typeof sequence.sectionChunkCount === "number" || sequence.sectionChunkId || typeof sequence.sectionChunkIndex === "number" ? sequence : undefined
+  };
+};
 var buildExcerpt2 = (text, maxLength = 160) => {
   const normalized = text.replaceAll(/\s+/g, " ").trim();
   if (normalized.length <= maxLength) {
@@ -1074,6 +1158,136 @@ var buildExcerpt2 = (text, maxLength = 160) => {
   }
   return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
 };
+var buildRAGChunkGraph = (chunks) => {
+  const nodes = [];
+  const edges = [];
+  const edgeKeys = new Set;
+  const sections = new Map;
+  for (const chunk of chunks) {
+    const labels = chunk.labels ?? buildRAGSourceLabels({
+      metadata: chunk.metadata,
+      source: chunk.source,
+      title: chunk.title
+    });
+    const structure = chunk.structure ?? buildRAGChunkStructure(chunk.metadata);
+    nodes.push({
+      chunkId: chunk.chunkId,
+      contextLabel: labels?.contextLabel,
+      label: chunk.source ?? chunk.title ?? chunk.chunkId,
+      locatorLabel: labels?.locatorLabel,
+      provenanceLabel: labels?.provenanceLabel,
+      score: chunk.score,
+      source: chunk.source,
+      structure,
+      title: chunk.title
+    });
+    const previousChunkId = structure?.sequence?.previousChunkId;
+    if (previousChunkId) {
+      const key = `previous:${previousChunkId}:${chunk.chunkId}`;
+      if (!edgeKeys.has(key)) {
+        edgeKeys.add(key);
+        edges.push({
+          fromChunkId: previousChunkId,
+          relation: "previous",
+          toChunkId: chunk.chunkId
+        });
+      }
+    }
+    const nextChunkId = structure?.sequence?.nextChunkId;
+    if (nextChunkId) {
+      const key = `next:${chunk.chunkId}:${nextChunkId}`;
+      if (!edgeKeys.has(key)) {
+        edgeKeys.add(key);
+        edges.push({
+          fromChunkId: chunk.chunkId,
+          relation: "next",
+          toChunkId: nextChunkId
+        });
+      }
+    }
+    const sectionId = structure?.sequence?.sectionChunkId;
+    if (sectionId) {
+      const existing = sections.get(sectionId);
+      if (!existing) {
+        sections.set(sectionId, {
+          chunkCount: structure.sequence?.sectionChunkCount ?? 1,
+          chunkIds: [chunk.chunkId],
+          depth: structure.section?.depth,
+          id: sectionId,
+          kind: structure.section?.kind,
+          path: structure.section?.path,
+          title: structure.section?.title
+        });
+        continue;
+      }
+      if (!existing.chunkIds.includes(chunk.chunkId)) {
+        existing.chunkIds.push(chunk.chunkId);
+      }
+      existing.chunkCount = Math.max(existing.chunkCount, structure.sequence?.sectionChunkCount ?? existing.chunkCount);
+    }
+  }
+  for (const section of sections.values()) {
+    section.chunkIds.sort((left, right) => {
+      const leftNode = nodes.find((node) => node.chunkId === left);
+      const rightNode = nodes.find((node) => node.chunkId === right);
+      const leftIndex = leftNode?.structure?.sequence?.sectionChunkIndex ?? Number.MAX_SAFE_INTEGER;
+      const rightIndex = rightNode?.structure?.sequence?.sectionChunkIndex ?? Number.MAX_SAFE_INTEGER;
+      if (leftIndex !== rightIndex) {
+        return leftIndex - rightIndex;
+      }
+      return left.localeCompare(right);
+    });
+  }
+  nodes.sort((left, right) => {
+    const leftSection = left.structure?.sequence?.sectionChunkIndex ?? Number.MAX_SAFE_INTEGER;
+    const rightSection = right.structure?.sequence?.sectionChunkIndex ?? Number.MAX_SAFE_INTEGER;
+    if (leftSection !== rightSection) {
+      return leftSection - rightSection;
+    }
+    const leftScore = left.score ?? Number.NEGATIVE_INFINITY;
+    const rightScore = right.score ?? Number.NEGATIVE_INFINITY;
+    if (leftScore !== rightScore) {
+      return rightScore - leftScore;
+    }
+    return left.label.localeCompare(right.label);
+  });
+  return {
+    edges,
+    nodes,
+    sections: [...sections.values()].sort((left, right) => (left.title ?? left.id).localeCompare(right.title ?? right.id))
+  };
+};
+var buildRAGChunkPreviewGraph = (preview) => buildRAGChunkGraph(preview.chunks.map((chunk) => ({
+  chunkId: chunk.chunkId,
+  labels: chunk.labels,
+  metadata: chunk.metadata,
+  source: chunk.source ?? preview.document.source,
+  structure: chunk.structure,
+  title: chunk.title ?? preview.document.title
+})));
+var buildRAGChunkPreviewNavigation = (preview, activeChunkId) => buildRAGChunkGraphNavigation(buildRAGChunkPreviewGraph(preview), activeChunkId);
+var buildRAGChunkGraphNavigation = (graph, activeChunkId) => {
+  if (graph.nodes.length === 0) {
+    return {
+      activeChunkId,
+      sectionNodes: []
+    };
+  }
+  const activeNode = (activeChunkId ? graph.nodes.find((node) => node.chunkId === activeChunkId) : undefined) ?? graph.nodes[0];
+  const resolvedActiveChunkId = activeNode?.chunkId;
+  const previousNode = activeNode?.structure?.sequence?.previousChunkId ? graph.nodes.find((node) => node.chunkId === activeNode.structure?.sequence?.previousChunkId) : undefined;
+  const nextNode = activeNode?.structure?.sequence?.nextChunkId ? graph.nodes.find((node) => node.chunkId === activeNode.structure?.sequence?.nextChunkId) : undefined;
+  const section = activeNode?.structure?.sequence?.sectionChunkId ? graph.sections.find((entry) => entry.id === activeNode.structure?.sequence?.sectionChunkId) : undefined;
+  const sectionNodes = section ? section.chunkIds.map((chunkId) => graph.nodes.find((node) => node.chunkId === chunkId)).filter((node) => Boolean(node)) : activeNode ? [activeNode] : [];
+  return {
+    activeChunkId: resolvedActiveChunkId,
+    activeNode,
+    nextNode,
+    previousNode,
+    section,
+    sectionNodes
+  };
+};
 var buildRAGRetrievedState = (messages) => {
   const message = getLatestRetrievedMessage(messages);
   if (!message) {
@@ -1108,13 +1322,14 @@ var buildRAGSourceSummaries = (sources) => {
       citationNumbers: groupCitations.map((citation) => citationReferenceMap[citation.chunkId] ?? 0),
       citations: groupCitations,
       chunkIds: group.chunks.map((chunk) => chunk.chunkId),
-      contextLabel: buildContextLabel2(leadChunk?.metadata),
+      contextLabel: leadChunk?.labels?.contextLabel ?? buildContextLabel2(leadChunk?.metadata),
       count: group.count,
       excerpt: buildExcerpt2(leadChunk?.text ?? ""),
       key: group.key,
       label: group.label,
-      locatorLabel: buildLocatorLabel2(leadChunk?.metadata, leadChunk?.source, leadChunk?.title),
-      provenanceLabel: buildProvenanceLabel2(leadChunk?.metadata),
+      locatorLabel: leadChunk?.labels?.locatorLabel ?? buildLocatorLabel2(leadChunk?.metadata, leadChunk?.source, leadChunk?.title),
+      provenanceLabel: leadChunk?.labels?.provenanceLabel ?? buildProvenanceLabel2(leadChunk?.metadata),
+      structure: leadChunk?.structure ?? buildRAGChunkStructure(leadChunk?.metadata),
       source: group.source,
       title: group.title
     };
@@ -1238,6 +1453,12 @@ var buildSourceGroup = (source, key) => ({
   count: 1,
   key,
   label: buildSourceLabel2(source),
+  labels: source.labels ?? buildRAGSourceLabels({
+    metadata: source.metadata,
+    source: source.source,
+    title: source.title
+  }),
+  structure: source.structure ?? buildRAGChunkStructure(source.metadata),
   source: source.source,
   title: source.title
 });
@@ -1248,7 +1469,20 @@ var updateSourceGroup = (groups, source) => {
     groups.set(key, buildSourceGroup(source, key));
     return;
   }
-  existing.bestScore = Math.max(existing.bestScore, source.score);
+  if (source.score > existing.bestScore) {
+    existing.bestScore = source.score;
+    existing.label = buildSourceLabel2(source);
+    existing.labels = source.labels ?? buildRAGSourceLabels({
+      metadata: source.metadata,
+      source: source.source,
+      title: source.title
+    });
+    existing.structure = source.structure ?? buildRAGChunkStructure(source.metadata);
+    existing.source = source.source;
+    existing.title = source.title;
+  } else {
+    existing.bestScore = Math.max(existing.bestScore, source.score);
+  }
   existing.count += 1;
   existing.chunks.push(source);
 };
@@ -2752,6 +2986,7 @@ var runRAGEvaluationSuite = async ({
 var useRAGChunkPreview = (path) => {
   const client = useMemo(() => createRAGClient({ path }), [path]);
   const [preview, setPreview] = useState(null);
+  const [activeChunkId, setActiveChunkId] = useState(null);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState(null);
   const inspect = useCallback2(async (id) => {
@@ -2763,6 +2998,7 @@ var useRAGChunkPreview = (path) => {
         throw new Error(response.error);
       }
       setPreview(response);
+      setActiveChunkId(response.chunks[0]?.chunkId ?? null);
       return response;
     } catch (err) {
       const message = err instanceof Error ? err.message : "Failed to load RAG chunk preview";
@@ -2774,15 +3010,25 @@ var useRAGChunkPreview = (path) => {
   }, [client]);
   const clear = useCallback2(() => {
     setPreview(null);
+    setActiveChunkId(null);
     setError(null);
     setIsLoading(false);
   }, []);
+  const chunkGraph = useMemo(() => preview ? buildRAGChunkPreviewGraph(preview) : null, [preview]);
+  const navigation = useMemo(() => preview ? buildRAGChunkPreviewNavigation(preview, activeChunkId ?? undefined) : null, [activeChunkId, preview]);
+  const selectChunk = useCallback2((id) => {
+    setActiveChunkId(id);
+  }, []);
   return {
+    activeChunkId,
+    chunkGraph,
     clear,
     error,
     inspect,
     isLoading,
-    preview
+    navigation,
+    preview,
+    selectChunk
   };
 };
 // src/react/ai/useRAG.ts
@@ -3363,9 +3609,11 @@ var useRAGSources = (messages) => {
   const sources = useMemo10(() => getLatestRAGSources(messages), [messages]);
   const sourceGroups = useMemo10(() => buildRAGSourceGroups(sources), [sources]);
   const sourceSummaries = useMemo10(() => buildRAGSourceSummaries(sources), [sources]);
+  const chunkGraph = useMemo10(() => buildRAGChunkGraph(sources), [sources]);
   const citationReferenceMap = useMemo10(() => buildRAGCitationReferenceMap(sourceSummaries.flatMap((summary) => summary.citations)), [sourceSummaries]);
   return {
     citationReferenceMap,
+    chunkGraph,
     hasSources: sources.length > 0,
     latestAssistantMessage,
     sourceGroups,