@absolutejs/absolute 0.19.0-beta.604 → 0.19.0-beta.606

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

@@ -725,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) => {
@@ -774,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) => {
@@ -823,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),
@@ -848,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,
@@ -923,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),
@@ -1020,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) => {
@@ -1059,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) => {
@@ -1104,6 +1124,33 @@ var buildRAGSourceLabels = ({
     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) {
@@ -1111,6 +1158,188 @@ 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, {
+          childSectionIds: [],
+          chunkCount: structure.sequence?.sectionChunkCount ?? 1,
+          chunkIds: [chunk.chunkId],
+          depth: structure.section?.depth,
+          id: sectionId,
+          kind: structure.section?.kind,
+          leadChunkId: chunk.chunkId,
+          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);
+    });
+    section.leadChunkId = section.chunkIds[0];
+  }
+  const sectionPathIndex = new Map;
+  for (const section of sections.values()) {
+    const path = section.path && section.path.length > 0 ? section.path : section.title ? [section.title] : undefined;
+    if (path && path.length > 0) {
+      sectionPathIndex.set(path.join("\x00"), section);
+    }
+  }
+  for (const section of sections.values()) {
+    const path = section.path && section.path.length > 0 ? section.path : section.title ? [section.title] : undefined;
+    if (!path || path.length < 2) {
+      continue;
+    }
+    const parent = sectionPathIndex.get(path.slice(0, -1).join("\x00"));
+    if (!parent || parent.id === section.id) {
+      continue;
+    }
+    section.parentSectionId = parent.id;
+    if (!parent.childSectionIds.includes(section.id)) {
+      parent.childSectionIds.push(section.id);
+    }
+    if (parent.leadChunkId && section.leadChunkId) {
+      const parentKey = `section_parent:${section.leadChunkId}:${parent.leadChunkId}`;
+      if (!edgeKeys.has(parentKey)) {
+        edgeKeys.add(parentKey);
+        edges.push({
+          fromChunkId: section.leadChunkId,
+          relation: "section_parent",
+          toChunkId: parent.leadChunkId
+        });
+      }
+      const childKey = `section_child:${parent.leadChunkId}:${section.leadChunkId}`;
+      if (!edgeKeys.has(childKey)) {
+        edgeKeys.add(childKey);
+        edges.push({
+          fromChunkId: parent.leadChunkId,
+          relation: "section_child",
+          toChunkId: section.leadChunkId
+        });
+      }
+    }
+  }
+  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,
+      childSections: [],
+      siblingSections: [],
+      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 parentSection = section?.parentSectionId ? graph.sections.find((entry) => entry.id === section.parentSectionId) : undefined;
+  const childSections = section ? section.childSectionIds.map((sectionId) => graph.sections.find((entry) => entry.id === sectionId)).filter((entry) => Boolean(entry)) : [];
+  const siblingSections = section?.parentSectionId ? graph.sections.filter((entry) => entry.parentSectionId === section.parentSectionId && entry.id !== section.id) : [];
+  const sectionNodes = section ? section.chunkIds.map((chunkId) => graph.nodes.find((node) => node.chunkId === chunkId)).filter((node) => Boolean(node)) : activeNode ? [activeNode] : [];
+  return {
+    activeChunkId: resolvedActiveChunkId,
+    activeNode,
+    childSections,
+    nextNode,
+    parentSection,
+    previousNode,
+    section,
+    siblingSections,
+    sectionNodes
+  };
+};
 var buildRAGRetrievedState = (messages) => {
   const message = getLatestRetrievedMessage(messages);
   if (!message) {
@@ -1152,6 +1381,7 @@ var buildRAGSourceSummaries = (sources) => {
       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),
       source: group.source,
       title: group.title
     };
@@ -1280,6 +1510,7 @@ var buildSourceGroup = (source, key) => ({
     source: source.source,
     title: source.title
   }),
+  structure: source.structure ?? buildRAGChunkStructure(source.metadata),
   source: source.source,
   title: source.title
 });
@@ -1298,6 +1529,7 @@ var updateSourceGroup = (groups, source) => {
       source: source.source,
       title: source.title
     });
+    existing.structure = source.structure ?? buildRAGChunkStructure(source.metadata);
     existing.source = source.source;
     existing.title = source.title;
   } else {
@@ -2806,6 +3038,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) => {
@@ -2817,6 +3050,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";
@@ -2828,15 +3062,46 @@ 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);
+  }, []);
+  const selectParentSection = useCallback2(() => {
+    const leadChunkId = navigation?.parentSection?.leadChunkId;
+    if (leadChunkId) {
+      setActiveChunkId(leadChunkId);
+    }
+  }, [navigation]);
+  const selectChildSection = useCallback2((sectionId) => {
+    const leadChunkId = navigation?.childSections.find((section) => section.id === sectionId)?.leadChunkId;
+    if (leadChunkId) {
+      setActiveChunkId(leadChunkId);
+    }
+  }, [navigation]);
+  const selectSiblingSection = useCallback2((sectionId) => {
+    const leadChunkId = navigation?.siblingSections.find((section) => section.id === sectionId)?.leadChunkId;
+    if (leadChunkId) {
+      setActiveChunkId(leadChunkId);
+    }
+  }, [navigation]);
   return {
+    activeChunkId,
+    chunkGraph,
     clear,
     error,
     inspect,
     isLoading,
-    preview
+    navigation,
+    preview,
+    selectChildSection,
+    selectChunk,
+    selectParentSection,
+    selectSiblingSection
   };
 };
 // src/react/ai/useRAG.ts
@@ -3411,17 +3676,21 @@ var useRAGSearch = (path) => {
 };
 
 // src/react/ai/useRAGSources.ts
-import { useMemo as useMemo10 } from "react";
+import { useCallback as useCallback9, useMemo as useMemo10 } from "react";
 var useRAGSources = (messages) => {
   const latestAssistantMessage = useMemo10(() => getLatestAssistantMessage(messages), [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]);
+  const navigationForChunk = useCallback9((chunkId) => buildRAGChunkGraphNavigation(chunkGraph, chunkId ?? undefined), [chunkGraph]);
   return {
     citationReferenceMap,
+    chunkGraph,
     hasSources: sources.length > 0,
     latestAssistantMessage,
+    navigationForChunk,
     sourceGroups,
     sources,
     sourceSummaries
@@ -3429,14 +3698,14 @@ var useRAGSources = (messages) => {
 };
 
 // src/react/ai/useRAGStatus.ts
-import { useCallback as useCallback9, useEffect as useEffect4, useMemo as useMemo11, useState as useState8 } from "react";
+import { useCallback as useCallback10, useEffect as useEffect4, useMemo as useMemo11, useState as useState8 } from "react";
 var useRAGStatus = (path, autoLoad = true) => {
   const client = useMemo11(() => createRAGClient({ path }), [path]);
   const [status, setStatus] = useState8();
   const [capabilities, setCapabilities] = useState8();
   const [error, setError] = useState8(null);
   const [isLoading, setIsLoading] = useState8(autoLoad);
-  const refresh = useCallback9(async () => {
+  const refresh = useCallback10(async () => {
     setIsLoading(true);
     setError(null);
     try {
@@ -3452,7 +3721,7 @@ var useRAGStatus = (path, autoLoad = true) => {
       setIsLoading(false);
     }
   }, [client]);
-  const reset = useCallback9(() => {
+  const reset = useCallback10(() => {
     setCapabilities(undefined);
     setError(null);
     setIsLoading(false);
@@ -3479,7 +3748,7 @@ var useRAGStatus = (path, autoLoad = true) => {
 import { useMemo as useMemo13 } from "react";
 
 // src/react/ai/useRAGStream.ts
-import { useCallback as useCallback10, useMemo as useMemo12 } from "react";
+import { useCallback as useCallback11, useMemo as useMemo12 } from "react";
 var useRAGStream = (path, conversationId) => {
   const stream = useAIStream(path, conversationId);
   const workflow = useMemo12(() => buildRAGAnswerWorkflowState({
@@ -3509,7 +3778,7 @@ var useRAGStream = (path, conversationId) => {
     sourceCount: workflow.sources.length,
     stage: workflow.stage
   }), [workflow]);
-  const query = useCallback10((content, attachments) => {
+  const query = useCallback11((content, attachments) => {
     stream.send(content, attachments);
   }, [stream]);
   return {