@trustgraph/react-state 1.5.2 → 1.5.4

package/dist/index.esm.js

@@ -1,7 +1,9 @@
 import { useSocket, useConnectionState } from '@trustgraph/react-provider';
 export { ConnectionStateContext, SocketContext, SocketProvider } from '@trustgraph/react-provider';
+import { TG_EDGE, TG_REASONING, TG_EDGE_COUNT, TG_SELECTED_EDGE, TG_QUERY, PROV_STARTED_AT_TIME, TG_CONTENT, RDFS_LABEL as RDFS_LABEL$2, PROV_WAS_DERIVED_FROM, TG_REIFIES } from '@trustgraph/client';
+export { PROV, PROV_ACTIVITY, PROV_ENTITY, PROV_STARTED_AT_TIME, PROV_WAS_DERIVED_FROM, PROV_WAS_GENERATED_BY, RDF, RDFS, RDF_TYPE, SCHEMA, SCHEMA_AUTHOR, SCHEMA_DESCRIPTION, SCHEMA_KEYWORDS, SCHEMA_NAME, SKOS, SKOS_DEFINITION, TG, TG_CONTENT, TG_DOCUMENT, TG_EDGE, TG_EDGE_COUNT, TG_QUERY, TG_REASONING, TG_REIFIES, TG_SELECTED_EDGE } from '@trustgraph/client';
 import { jsx } from 'react/jsx-runtime';
-import { createContext, useContext, useEffect, useState, useMemo } from 'react';
+import { createContext, useContext, useEffect, useState, useRef, useCallback, useMemo } from 'react';
 import { create } from 'zustand';
 import { useQueryClient, useQuery, useMutation } from '@tanstack/react-query';
 import { v4 } from 'uuid';
@@ -155,23 +157,25 @@ const useConversation = create()((set) => ({
     setMessages: (v) => set(() => ({
         messages: v,
     })),
-    addMessage: (role, text, type) => set((state) => ({
+    addMessage: (role, text, type, explainSessionId) => set((state) => ({
         messages: [
             ...state.messages,
             {
                 role: role,
                 text: text,
                 type: type || "normal",
+                explainSessionId,
             },
         ],
     })),
-    updateLastMessage: (text) => set((state) => {
+    updateLastMessage: (text, explainSessionId) => set((state) => {
         if (state.messages.length === 0)
             return state;
         const messages = [...state.messages];
         messages[messages.length - 1] = {
             ...messages[messages.length - 1],
             text: text,
+            ...(explainSessionId !== undefined && { explainSessionId }),
         };
         return { messages };
     }),
@@ -311,6 +315,7 @@ const DEFAULT_SETTINGS = {
         flowBlueprintEditor: false, // Off by default - experimental feature
         structuredQuery: false, // Off by default
         llmModels: false, // Off by default
+        explainability: true, // On by default
     },
 };
 const SETTINGS_STORAGE_KEY = "trustgraph-settings";
@@ -967,7 +972,7 @@ const useTriples = ({ flow, s, p, o, limit, collection }) => {
 };
 
 // Helper to get the string value from a Term (IRI or Literal)
-const getTermValue$2 = (term) => {
+const getTermValue$3 = (term) => {
     if (term.t === "i")
         return term.i;
     if (term.t === "l")
@@ -1086,7 +1091,7 @@ const queryLabel = (socket, uri, add, remove, collection) => {
         // If got a result, return the label, otherwise the URI
         // can be its own label
         if (triples.length > 0)
-            return getTermValue$2(triples[0].o);
+            return getTermValue$3(triples[0].o);
         else
             return uri;
     })
@@ -1103,7 +1108,7 @@ const queryLabel = (socket, uri, add, remove, collection) => {
 // Returns a promise
 const labelS = (socket, triples, add, remove, collection) => {
     return Promise.all(triples.map((t) => {
-        return queryLabel(socket, getTermValue$2(t.s), add, remove, collection).then((label) => {
+        return queryLabel(socket, getTermValue$3(t.s), add, remove, collection).then((label) => {
             return {
                 ...t,
                 s: {
@@ -1118,7 +1123,7 @@ const labelS = (socket, triples, add, remove, collection) => {
 // Returns a promise
 const labelP = (socket, triples, add, remove, collection) => {
     return Promise.all(triples.map((t) => {
-        return queryLabel(socket, getTermValue$2(t.p), add, remove, collection).then((label) => {
+        return queryLabel(socket, getTermValue$3(t.p), add, remove, collection).then((label) => {
             return {
                 ...t,
                 p: {
@@ -1151,7 +1156,7 @@ const labelO = (socket, triples, add, remove, collection) => {
                     ...t,
                     o: {
                         ...t.o,
-                        label: getTermValue$2(t.o),
+                        label: getTermValue$3(t.o),
                     },
                 });
             });
@@ -1187,7 +1192,7 @@ const getTriples = (socket, uri, add, remove, limit, collection) => {
 // Functionality here helps construct subgraphs for react-force-graph
 // visualisation
 // Helper to get the string value from a Term (IRI or Literal)
-const getTermValue$1 = (term) => {
+const getTermValue$2 = (term) => {
     if (term.t === "i")
         return term.i;
     if (term.t === "l")
@@ -1215,11 +1220,11 @@ const updateSubgraphTriples = (sg, triples) => {
             continue;
         }
         // Source has a URI, that can be its unique ID
-        const sourceId = getTermValue$1(t.s);
+        const sourceId = getTermValue$2(t.s);
         // Target is always an entity now (we filtered out literals above)
-        const targetId = getTermValue$1(t.o);
+        const targetId = getTermValue$2(t.o);
         // Links have an ID so that this edge is unique
-        const linkId = getTermValue$1(t.s) + "@@" + getTermValue$1(t.p) + "@@" + getTermValue$1(t.o);
+        const linkId = getTermValue$2(t.s) + "@@" + getTermValue$2(t.p) + "@@" + getTermValue$2(t.o);
         if (!nodeIds.has(sourceId)) {
             const sLabeled = t.s;
             const n = {
@@ -1730,10 +1735,14 @@ const useInference = ({ flow } = {}) => {
     // Use explicit param if provided, otherwise fall back to session state
     const effectiveFlow = flow ?? sessionFlowId;
     /**
-     * Graph RAG inference with entity discovery
+     * Graph RAG inference with entity discovery and optional explainability
+     * Explainability events are only tracked if callbacks.onExplain is provided
      */
     const graphRagMutation = useMutation({
         mutationFn: async ({ input, options, collection, callbacks, }) => {
+            // Only collect explain events if caller provided onExplain callback
+            const wantsExplainability = !!callbacks?.onExplain;
+            const explainEvents = wantsExplainability ? [] : undefined;
             // If callbacks provided, use streaming API
             const response = callbacks
                 ? await new Promise((resolve, reject) => {
@@ -1749,9 +1758,16 @@ const useInference = ({ flow } = {}) => {
                         callbacks?.onError?.(error);
                         reject(new Error(error));
                     };
+                    // Only wire up onExplain if caller wants explainability
+                    const onExplain = wantsExplainability
+                        ? (event) => {
+                            explainEvents.push(event);
+                            callbacks.onExplain(event);
+                        }
+                        : undefined;
                     socket
                         .flow(effectiveFlow)
-                        .graphRagStreaming(input, onChunk, onError, options, collection);
+                        .graphRagStreaming(input, onChunk, onError, options, collection, onExplain);
                 })
                 : await socket.flow(effectiveFlow).graphRag(input, options || {}, collection);
             // Get embeddings for entity discovery
@@ -1761,7 +1777,7 @@ const useInference = ({ flow } = {}) => {
             const entities = await socket
                 .flow(effectiveFlow)
                 .graphEmbeddingsQuery(embeddings, options?.entityLimit || 10, collection);
-            return { response, entities };
+            return { response, entities, explainEvents };
         },
     });
     /**
@@ -1831,6 +1847,620 @@ const useInference = ({ flow } = {}) => {
     };
 };
 
+/**
+ * Zustand store for managing explainability sessions
+ * Sessions are keyed by ID and linked to messages via explainSessionId
+ */
+const useExplainabilityStore = create()((set, get) => ({
+    sessions: {},
+    addSession: (id, session) => set((state) => ({
+        sessions: {
+            ...state.sessions,
+            [id]: session,
+        },
+    })),
+    updateSession: (id, partial) => set((state) => ({
+        sessions: {
+            ...state.sessions,
+            [id]: {
+                ...state.sessions[id],
+                ...partial,
+            },
+        },
+    })),
+    getSession: (id) => get().sessions[id],
+    removeSession: (id) => set((state) => {
+        const { [id]: _, ...rest } = state.sessions;
+        return { sessions: rest };
+    }),
+    clearSessions: () => set({ sessions: {} }),
+}));
+
+/**
+ * Explainability utilities for parsing and structuring explain events
+ */
+/**
+ * Extract event type from explainId URI
+ * e.g., "urn:trustgraph:question:abc123" → "question"
+ */
+function getEventType(explainId) {
+    if (explainId.includes("question"))
+        return "question";
+    if (explainId.includes("exploration"))
+        return "exploration";
+    if (explainId.includes("focus"))
+        return "focus";
+    if (explainId.includes("synthesis"))
+        return "synthesis";
+    return "unknown";
+}
+/**
+ * Get term value from a Term object
+ */
+function getTermValue$1(term) {
+    if (!term)
+        return "";
+    if (term.t === "i")
+        return term.i || "";
+    if (term.t === "l")
+        return term.v || "";
+    if (term.t === "t" && term.tr) {
+        // Quoted triple - return a serialized form
+        const s = getTermValue$1(term.tr.s);
+        const p = getTermValue$1(term.tr.p);
+        const o = getTermValue$1(term.tr.o);
+        return `<<${s} ${p} ${o}>>`;
+    }
+    return "";
+}
+/**
+ * Extract quoted triple from a Term
+ */
+function extractQuotedTriple(term) {
+    if (term.t === "t" && term.tr) {
+        return {
+            s: getTermValue$1(term.tr.s),
+            p: getTermValue$1(term.tr.p),
+            o: getTermValue$1(term.tr.o),
+        };
+    }
+    return null;
+}
+/**
+ * Parse triples for a question event
+ */
+function parseQuestionTriples(explainId, explainGraph, triples) {
+    const event = {
+        type: "question",
+        explainId,
+        explainGraph,
+    };
+    for (const triple of triples) {
+        const p = getTermValue$1(triple.p);
+        const o = getTermValue$1(triple.o);
+        if (p === TG_QUERY) {
+            event.query = o;
+        }
+        else if (p === PROV_STARTED_AT_TIME) {
+            event.timestamp = o;
+        }
+    }
+    return event;
+}
+/**
+ * Parse triples for an exploration event
+ */
+function parseExplorationTriples(explainId, explainGraph, triples) {
+    const event = {
+        type: "exploration",
+        explainId,
+        explainGraph,
+    };
+    for (const triple of triples) {
+        const p = getTermValue$1(triple.p);
+        const o = getTermValue$1(triple.o);
+        if (p === TG_EDGE_COUNT) {
+            event.edgeCount = parseInt(o, 10);
+        }
+    }
+    return event;
+}
+/**
+ * Parse triples for a focus event
+ */
+function parseFocusTriples(explainId, explainGraph, triples) {
+    const event = {
+        type: "focus",
+        explainId,
+        explainGraph,
+        edgeSelectionUris: [],
+    };
+    for (const triple of triples) {
+        const p = getTermValue$1(triple.p);
+        const o = getTermValue$1(triple.o);
+        if (p === TG_SELECTED_EDGE && typeof o === "string") {
+            event.edgeSelectionUris.push(o);
+        }
+    }
+    return event;
+}
+/**
+ * Parse triples for a synthesis event
+ */
+function parseSynthesisTriples(explainId, explainGraph, triples) {
+    const event = {
+        type: "synthesis",
+        explainId,
+        explainGraph,
+    };
+    for (const triple of triples) {
+        const p = getTermValue$1(triple.p);
+        const o = getTermValue$1(triple.o);
+        if (p === TG_CONTENT) {
+            event.contentLength = o.length;
+        }
+    }
+    return event;
+}
+/**
+ * Parse triples for an edge selection entity
+ */
+function parseEdgeSelectionTriples(triples) {
+    let edge = null;
+    let reasoning = null;
+    for (const triple of triples) {
+        const p = getTermValue$1(triple.p);
+        if (p === TG_EDGE) {
+            edge = extractQuotedTriple(triple.o);
+        }
+        else if (p === TG_REASONING) {
+            reasoning = getTermValue$1(triple.o);
+        }
+    }
+    return { edge, reasoning };
+}
+/**
+ * Parse triples based on event type
+ */
+function parseExplainTriples(explainId, explainGraph, triples) {
+    const eventType = getEventType(explainId);
+    switch (eventType) {
+        case "question":
+            return parseQuestionTriples(explainId, explainGraph, triples);
+        case "exploration":
+            return parseExplorationTriples(explainId, explainGraph, triples);
+        case "focus":
+            return parseFocusTriples(explainId, explainGraph, triples);
+        case "synthesis":
+            return parseSynthesisTriples(explainId, explainGraph, triples);
+        default:
+            return null;
+    }
+}
+
+/**
+ * Hook for tracing provenance chains in the knowledge graph
+ * Follows prov:wasDerivedFrom relationships from any entity to its source documents
+ */
+/**
+ * Hook for tracing provenance chains
+ */
+const useProvenance = (options = {}) => {
+    const { flow, collection = "default", maxDepth = 10 } = options;
+    const socket = useSocket();
+    const connectionState = useConnectionState();
+    const sessionFlowId = useSessionStore((state) => state.flowId);
+    const effectiveFlow = flow ?? sessionFlowId;
+    const [isTracing, setIsTracing] = useState(false);
+    // Label cache to avoid repeated queries
+    const labelCacheRef = useRef(new Map());
+    /**
+     * Check if connected
+     */
+    const isConnected = useCallback(() => {
+        return (connectionState?.status === "authenticated" ||
+            connectionState?.status === "unauthenticated");
+    }, [connectionState]);
+    /**
+     * Query for rdfs:label of a URI
+     */
+    const resolveLabel = useCallback(async (uri) => {
+        // Check cache
+        if (labelCacheRef.current.has(uri)) {
+            return labelCacheRef.current.get(uri);
+        }
+        // Not an IRI - return as-is
+        if (!uri.startsWith("http") && !uri.startsWith("urn:")) {
+            return uri;
+        }
+        if (!isConnected()) {
+            return uri;
+        }
+        try {
+            const triples = await socket
+                .flow(effectiveFlow)
+                .triplesQuery({ t: "i", i: uri }, { t: "i", i: RDFS_LABEL$2 }, undefined, 1, collection);
+            const label = triples.length > 0 ? getTermValue$1(triples[0].o) : uri;
+            // Cache the result
+            labelCacheRef.current.set(uri, label);
+            return label;
+        }
+        catch {
+            return uri;
+        }
+    }, [socket, effectiveFlow, collection, isConnected]);
+    /**
+     * Query for prov:wasDerivedFrom parent of a URI
+     */
+    const queryDerivedFrom = useCallback(async (uri) => {
+        if (!isConnected())
+            return null;
+        try {
+            const triples = await socket
+                .flow(effectiveFlow)
+                .triplesQuery({ t: "i", i: uri }, { t: "i", i: PROV_WAS_DERIVED_FROM }, undefined, 1, collection);
+            if (triples.length > 0) {
+                return getTermValue$1(triples[0].o);
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }, [socket, effectiveFlow, collection, isConnected]);
+    /**
+     * Trace the full provenance chain from a URI to root
+     */
+    const traceChain = useCallback(async (uri) => {
+        setIsTracing(true);
+        try {
+            const chain = [];
+            let current = uri;
+            for (let depth = 0; depth < maxDepth && current; depth++) {
+                const label = await resolveLabel(current);
+                chain.push({ uri: current, label });
+                const parent = await queryDerivedFrom(current);
+                if (!parent || parent === current) {
+                    break;
+                }
+                current = parent;
+            }
+            // The last item in the chain is the root document
+            const rootItem = chain.length > 0 ? chain[chain.length - 1] : undefined;
+            return {
+                chain,
+                documentUri: rootItem?.uri,
+                documentLabel: rootItem?.label,
+            };
+        }
+        finally {
+            setIsTracing(false);
+        }
+    }, [maxDepth, resolveLabel, queryDerivedFrom]);
+    /**
+     * Query for statements that reify an edge via tg:reifies
+     */
+    const queryReifyingStatements = useCallback(async (s, p, o) => {
+        if (!isConnected())
+            return [];
+        try {
+            // Build the quoted triple term
+            const quotedTriple = {
+                t: "t",
+                tr: {
+                    s: { t: "i", i: s },
+                    p: { t: "i", i: p },
+                    o: o.startsWith("http") || o.startsWith("urn:")
+                        ? { t: "i", i: o }
+                        : { t: "l", v: o },
+                },
+            };
+            const triples = await socket
+                .flow(effectiveFlow)
+                .triplesQuery(undefined, { t: "i", i: TG_REIFIES }, quotedTriple, 10, collection);
+            return triples.map((t) => getTermValue$1(t.s));
+        }
+        catch {
+            return [];
+        }
+    }, [socket, effectiveFlow, collection, isConnected]);
+    /**
+     * Trace provenance for an edge - finds reifying statements and traces each
+     */
+    const traceEdgeProvenance = useCallback(async (s, p, o) => {
+        setIsTracing(true);
+        try {
+            // Find statements that reify this edge
+            const stmtUris = await queryReifyingStatements(s, p, o);
+            // For each reifying statement, trace its provenance chain
+            const chains = [];
+            for (const stmtUri of stmtUris) {
+                // Get the wasDerivedFrom source for this statement
+                const sourceUri = await queryDerivedFrom(stmtUri);
+                if (sourceUri) {
+                    const chain = await traceChain(sourceUri);
+                    chains.push(chain);
+                }
+            }
+            return chains;
+        }
+        finally {
+            setIsTracing(false);
+        }
+    }, [queryReifyingStatements, queryDerivedFrom, traceChain]);
+    /**
+     * Clear the label cache
+     */
+    const clearCache = useCallback(() => {
+        labelCacheRef.current.clear();
+    }, []);
+    return {
+        traceChain,
+        traceEdgeProvenance,
+        resolveLabel,
+        clearCache,
+        isTracing,
+    };
+};
+
+/**
+ * Hook for managing explainability state during GraphRAG queries
+ * Unpacks explain events into structured data with provenance chains
+ *
+ * Processing strategy:
+ * - Events are processed immediately as they arrive
+ * - Main event nodes (question, exploration, focus, synthesis) use
+ *   stability-based retry: fetch until count > 0 AND stable
+ * - Edge sub-objects use simple retry-until-non-empty (fast)
+ * - All edge fetching + label resolution + provenance runs in parallel
+ */
+/**
+ * Hook for managing explainability during inference
+ */
+const useExplainability = (options = {}) => {
+    const { flow, collection = "default", traceProvenance = true, } = options;
+    const socket = useSocket();
+    const connectionState = useConnectionState();
+    const sessionFlowId = useSessionStore((state) => state.flowId);
+    const effectiveFlow = flow ?? sessionFlowId;
+    const { traceEdgeProvenance, resolveLabel } = useProvenance({
+        flow: effectiveFlow,
+        collection,
+    });
+    const [events, setEvents] = useState([]);
+    const [session, setSession] = useState({});
+    const [isUnpacking, setIsUnpacking] = useState(false);
+    const [error, setError] = useState(null);
+    // Mirror session in a ref so it's always immediately readable (no render delay)
+    const sessionRef = useRef({});
+    // Track pending unpack operations
+    const unpackQueueRef = useRef([]);
+    const isProcessingRef = useRef(false);
+    /**
+     * Check if connected
+     */
+    const isConnected = useCallback(() => {
+        return (connectionState?.status === "authenticated" ||
+            connectionState?.status === "unauthenticated");
+    }, [connectionState]);
+    /**
+     * Single triple query (no retry)
+     */
+    const fetchTriples = useCallback(async (explainId, explainGraph) => {
+        return socket
+            .flow(effectiveFlow)
+            .triplesQuery({ t: "i", i: explainId }, undefined, undefined, 100, collection, explainGraph);
+    }, [socket, effectiveFlow, collection]);
+    /**
+     * Stability-based retry for main event nodes.
+     * Retries until: count > 0 AND count matches previous fetch.
+     * Used for question, exploration, focus, synthesis nodes where the
+     * backend may write multiple triples incrementally.
+     */
+    const queryWithStabilityRetry = useCallback(async (explainId, explainGraph, timeoutMs = 5000) => {
+        if (!isConnected())
+            return [];
+        const retryDelay = 500;
+        const maxAttempts = Math.ceil(timeoutMs / retryDelay) + 1;
+        let prevCount = -1;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                const triples = await fetchTriples(explainId, explainGraph);
+                const count = triples.length;
+                if (count > 0 && count === prevCount) {
+                    return triples;
+                }
+                prevCount = count;
+                if (attempt < maxAttempts - 1) {
+                    await new Promise((r) => setTimeout(r, retryDelay));
+                }
+            }
+            catch (err) {
+                console.error("[explain] triple query failed:", explainId, err);
+                return [];
+            }
+        }
+        // Return last fetch if we got anything
+        if (prevCount > 0) {
+            try {
+                return await fetchTriples(explainId, explainGraph);
+            }
+            catch {
+                return [];
+            }
+        }
+        return [];
+    }, [fetchTriples, isConnected]);
+    /**
+     * Simple retry-until-non-empty for sub-objects (edge selections).
+     * These are small atomic writes — either fully there or not yet.
+     */
+    const queryWithSimpleRetry = useCallback(async (explainId, explainGraph, timeoutMs = 5000) => {
+        if (!isConnected())
+            return [];
+        const retryDelay = 300;
+        const maxAttempts = Math.ceil(timeoutMs / retryDelay) + 1;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                const triples = await fetchTriples(explainId, explainGraph);
+                if (triples.length > 0)
+                    return triples;
+                if (attempt < maxAttempts - 1) {
+                    await new Promise((r) => setTimeout(r, retryDelay));
+                }
+            }
+            catch (err) {
+                console.error("[explain] triple query failed:", explainId, err);
+                return [];
+            }
+        }
+        return [];
+    }, [fetchTriples, isConnected]);
+    /**
+     * Resolve a single edge: fetch triples, labels, and provenance in parallel
+     */
+    const resolveEdge = useCallback(async (edgeSelUri, explainGraph) => {
+        const triples = await queryWithSimpleRetry(edgeSelUri, explainGraph);
+        const { edge, reasoning } = parseEdgeSelectionTriples(triples);
+        if (!edge)
+            return null;
+        const selectedEdge = {
+            edge,
+            reasoning: reasoning || undefined,
+        };
+        // Kick off labels and provenance in parallel
+        const [labels, provenanceChains] = await Promise.all([
+            // Labels — all 3 in parallel
+            Promise.all([
+                resolveLabel(edge.s),
+                resolveLabel(edge.p),
+                resolveLabel(edge.o),
+            ]),
+            // Provenance
+            traceProvenance
+                ? traceEdgeProvenance(edge.s, edge.p, edge.o)
+                : Promise.resolve([]),
+        ]);
+        selectedEdge.labels = { s: labels[0], p: labels[1], o: labels[2] };
+        if (provenanceChains.length > 0) {
+            selectedEdge.sources = provenanceChains.map((c) => c.chain).flat();
+        }
+        return selectedEdge;
+    }, [queryWithSimpleRetry, resolveLabel, traceProvenance, traceEdgeProvenance]);
+    /**
+     * Unpack a focus event — resolve ALL edges in parallel
+     */
+    const unpackFocusEvent = useCallback(async (focusEvent) => {
+        // Fire off all edge resolutions concurrently
+        const edgePromises = focusEvent.edgeSelectionUris.map((uri) => resolveEdge(uri, focusEvent.explainGraph));
+        const results = await Promise.all(edgePromises);
+        const selectedEdges = results.filter((e) => e !== null);
+        return {
+            ...focusEvent,
+            selectedEdges,
+        };
+    }, [resolveEdge]);
+    /** Helper to update both state and ref together */
+    const updateSession = useCallback((updater) => {
+        sessionRef.current = updater(sessionRef.current);
+        setSession(updater);
+    }, []);
+    /**
+     * Process a single explain event
+     */
+    const processEvent = useCallback(async (event) => {
+        // Query triples for main event node (stability retry)
+        const triples = await queryWithStabilityRetry(event.explainId, event.explainGraph);
+        // Parse into structured data
+        const parsed = parseExplainTriples(event.explainId, event.explainGraph, triples);
+        if (!parsed)
+            return;
+        // Update session based on event type
+        updateSession((prev) => {
+            const next = { ...prev };
+            switch (parsed.type) {
+                case "question":
+                    next.question = parsed;
+                    break;
+                case "exploration":
+                    next.exploration = parsed;
+                    break;
+                case "focus":
+                    // Will be updated again after unpacking
+                    next.focus = parsed;
+                    break;
+                case "synthesis":
+                    next.synthesis = parsed;
+                    break;
+            }
+            return next;
+        });
+        // For focus events, unpack edges in parallel
+        if (parsed.type === "focus") {
+            const unpackedFocus = await unpackFocusEvent(parsed);
+            updateSession((prev) => ({
+                ...prev,
+                focus: unpackedFocus,
+            }));
+        }
+    }, [queryWithStabilityRetry, unpackFocusEvent, updateSession]);
+    /**
+     * Process the unpack queue
+     */
+    const processQueue = useCallback(async () => {
+        if (isProcessingRef.current)
+            return;
+        if (unpackQueueRef.current.length === 0)
+            return;
+        isProcessingRef.current = true;
+        setIsUnpacking(true);
+        try {
+            while (unpackQueueRef.current.length > 0) {
+                const event = unpackQueueRef.current.shift();
+                await processEvent(event);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            setError(msg);
+        }
+        isProcessingRef.current = false;
+        setIsUnpacking(false);
+        // Check if more events were queued during processing (e.g., after a reset)
+        if (unpackQueueRef.current.length > 0) {
+            processQueue();
+        }
+    }, [processEvent]);
+    /**
+     * Add an explain event — immediately queues and starts processing
+     */
+    const addEvent = useCallback((event) => {
+        setEvents((prev) => [...prev, event]);
+        unpackQueueRef.current.push(event);
+        processQueue();
+    }, [processQueue]);
+    /**
+     * Reset the session
+     */
+    const reset = useCallback(() => {
+        setEvents([]);
+        setSession({});
+        sessionRef.current = {};
+        setError(null);
+        unpackQueueRef.current = [];
+    }, []);
+    return {
+        addEvent,
+        session,
+        sessionRef,
+        events,
+        isUnpacking,
+        isProcessingRef,
+        error,
+        reset,
+    };
+};
+
 /**
  * High-level hook for managing chat sessions
  * Combines conversation state with inference services
@@ -1854,6 +2484,19 @@ const useChatSession = ({ flow } = {}) => {
     const effectiveFlow = flow ?? sessionFlowId;
     // Settings for GraphRAG configuration
     const { settings } = useSettings();
+    // Explainability store for persisting sessions
+    const addExplainSession = useExplainabilityStore((state) => state.addSession);
+    // Explainability hook for processing events (processes each event immediately)
+    const explainability = useExplainability({
+        flow: effectiveFlow,
+        collection: settings.collection,
+    });
+    const explainabilityRef = useRef(explainability);
+    explainabilityRef.current = explainability;
+    // Generate unique session IDs
+    const generateSessionId = useCallback(() => {
+        return `explain-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }, []);
     // Inference services
     const inference = useInference({ flow });
     /**
@@ -1865,6 +2508,13 @@ const useChatSession = ({ flow } = {}) => {
         addActivity(ragActivity);
         let accumulated = "";
         let messageAdded = false;
+        // Check if explainability is enabled
+        const explainabilityEnabled = settings.featureSwitches.explainability;
+        const sessionId = explainabilityEnabled ? generateSessionId() : undefined;
+        // Reset explainability state for new query
+        if (explainabilityEnabled) {
+            explainabilityRef.current.reset();
+        }
         try {
             // Execute Graph RAG with streaming and entity discovery
             const result = await inference.graphRag({
@@ -1880,8 +2530,8 @@ const useChatSession = ({ flow } = {}) => {
                     onChunk: (chunk, complete) => {
                         accumulated += chunk;
                         if (!messageAdded) {
-                            // Add empty message on first chunk
-                            addMessage("ai", accumulated);
+                            // Add empty message on first chunk (with session ID if enabled)
+                            addMessage("ai", accumulated, undefined, sessionId);
                             messageAdded = true;
                         }
                         else {
@@ -1889,9 +2539,32 @@ const useChatSession = ({ flow } = {}) => {
                             updateLastMessage(accumulated);
                         }
                     },
+                    // Wire up explainability callback if feature is enabled
+                    ...(explainabilityEnabled && {
+                        onExplain: (event) => {
+                            console.log("[explain] event received:", event.explainId);
+                            explainabilityRef.current.addEvent(event);
+                        },
+                    }),
                 },
             });
             removeActivity(ragActivity);
+            // Store explainability session progressively — events are already being
+            // processed as they arrive. Wait for processing to finish, then snapshot.
+            if (explainabilityEnabled && sessionId) {
+                const waitAndStore = async () => {
+                    // Poll until processing completes (events are processed as they arrive)
+                    const maxWait = 30000;
+                    let elapsed = 0;
+                    while (explainabilityRef.current.isProcessingRef.current && elapsed < maxWait) {
+                        await new Promise((r) => setTimeout(r, 500));
+                        elapsed += 500;
+                    }
+                    const sess = explainabilityRef.current.sessionRef.current;
+                    addExplainSession(sessionId, sess);
+                };
+                waitAndStore();
+            }
             // Start embeddings activity
             addActivity(embActivity);
             // Get labels for each entity
@@ -1899,7 +2572,7 @@ const useChatSession = ({ flow } = {}) => {
                 .filter((match) => match.entity !== null)
                 .map(async (match) => {
                 const entity = match.entity;
-                const labelActivity = "Label " + getTermValue$2(entity);
+                const labelActivity = "Label " + getTermValue$3(entity);
                 addActivity(labelActivity);
                 try {
                     const triples = await socket
@@ -1918,8 +2591,8 @@ const useChatSession = ({ flow } = {}) => {
             const entityList = labelResponses
                 .filter((resp) => resp && resp.length > 0)
                 .map((resp) => ({
-                label: getTermValue$2(resp[0].o),
-                uri: getTermValue$2(resp[0].s),
+                label: getTermValue$3(resp[0].o),
+                uri: getTermValue$3(resp[0].s),
             }));
             setEntities(entityList);
             removeActivity(embActivity);
@@ -4641,5 +5314,622 @@ const useNodeDetails = (nodeId, flowId) => {
     };
 };
 
-export { DEFAULT_SETTINGS, NotificationProvider, RDFS_LABEL, SETTINGS_STORAGE_KEY, createDocId, fileToBase64, generateFlowBlueprintId, getTermValue$2 as getTermValue, getTriples, prepareMetadata, textToBase64, useActivity, useAgentTools, useChat, useChatSession, useCollections, useConversation, useDocumentEmbeddingsQuery, useEmbeddings, useEntityDetail, useFlowBlueprints, useFlowParameters, useFlows, useGraphEmbeddings, useGraphSubgraph, useInference, useKnowledgeCores, useLLMModels, useLibrary, useLoadStateStore, useMcpTools, useNlpQuery, useNodeDetails, useNotification, useOntologies, useParameterValidation, useProcessing, useProgressStateStore, usePrompts, useRowEmbeddingsQuery, useRowsQuery, useSchemas, useSearchStateStore, useSessionStore, useSettings, useStructuredQuery, useTokenCosts, useTriples, useVectorSearch, useWorkbenchStateStore, vectorSearch };
+// Default chunk size: 5MB (matches backend default)
+const DEFAULT_CHUNK_SIZE$1 = 5 * 1024 * 1024;
+// Maximum parallel chunk uploads
+const DEFAULT_PARALLEL_UPLOADS = 3;
+/**
+ * Hook for managing chunked document uploads with progress tracking
+ *
+ * Features:
+ * - Automatic chunking of large files
+ * - Parallel chunk uploads for performance
+ * - Progress tracking (bytes, percentage, chunks)
+ * - Pause/resume support
+ * - Cancel support
+ * - Resumability after interruption
+ *
+ * @param options - Configuration options for the upload
+ * @returns Upload state and control methods
+ */
+const useChunkedUpload = (options = {}) => {
+    const { chunkSize = DEFAULT_CHUNK_SIZE$1, parallelUploads = DEFAULT_PARALLEL_UPLOADS, onProgress, onComplete, onError, } = options;
+    const socket = useSocket();
+    const connectionState = useConnectionState();
+    const queryClient = useQueryClient();
+    const notify = useNotification();
+    // Upload state
+    const [progress, setProgress] = useState({
+        totalBytes: 0,
+        bytesUploaded: 0,
+        percentage: 0,
+        totalChunks: 0,
+        chunksUploaded: 0,
+        pendingChunks: [],
+        status: "idle",
+    });
+    // Refs for managing upload lifecycle
+    const abortControllerRef = useRef(null);
+    const isPausedRef = useRef(false);
+    const currentFileRef = useRef(null);
+    const uploadIdRef = useRef(null);
+    // Update progress and notify callback
+    const updateProgress = useCallback((updates) => {
+        setProgress((prev) => {
+            const next = { ...prev, ...updates };
+            onProgress?.(next);
+            return next;
+        });
+    }, [onProgress]);
+    // Read a chunk from the file as base64
+    const readChunkAsBase64 = useCallback(async (file, chunkIndex, chunkSz) => {
+        const start = chunkIndex * chunkSz;
+        const end = Math.min(start + chunkSz, file.size);
+        const blob = file.slice(start, end);
+        return new Promise((resolve, reject) => {
+            const reader = new FileReader();
+            reader.onloadend = () => {
+                const dataUrl = reader.result;
+                // Extract base64 from data URL
+                const base64 = dataUrl.replace(/^data:[^;]+;base64,/, "");
+                resolve(base64);
+            };
+            reader.onerror = () => reject(new Error("Failed to read file chunk"));
+            reader.readAsDataURL(blob);
+        });
+    }, []);
+    // Upload chunks in parallel with concurrency limit
+    const uploadChunks = useCallback(async (file, uploadId, pendingChunks, chunkSz, totalChunks) => {
+        const remaining = [...pendingChunks];
+        let completedCount = totalChunks - remaining.length;
+        let bytesUploaded = completedCount * chunkSz;
+        // Process chunks with limited parallelism
+        const uploadNextBatch = async () => {
+            while (remaining.length > 0 && !abortControllerRef.current?.signal.aborted) {
+                // Wait if paused
+                if (isPausedRef.current) {
+                    await new Promise((resolve) => setTimeout(resolve, 100));
+                    continue;
+                }
+                // Take up to parallelUploads chunks
+                const batch = remaining.splice(0, parallelUploads);
+                // Upload batch in parallel
+                const results = await Promise.allSettled(batch.map(async (chunkIndex) => {
+                    const content = await readChunkAsBase64(file, chunkIndex, chunkSz);
+                    await socket.librarian().uploadChunk(uploadId, chunkIndex, content);
+                    return chunkIndex;
+                }));
+                // Process results
+                for (const result of results) {
+                    if (result.status === "fulfilled") {
+                        completedCount++;
+                        // Calculate actual bytes for this chunk
+                        const chunkIdx = result.value;
+                        const chunkStart = chunkIdx * chunkSz;
+                        const chunkEnd = Math.min(chunkStart + chunkSz, file.size);
+                        bytesUploaded += chunkEnd - chunkStart;
+                        updateProgress({
+                            chunksUploaded: completedCount,
+                            bytesUploaded,
+                            percentage: Math.round((bytesUploaded / file.size) * 100),
+                            pendingChunks: [...remaining],
+                        });
+                    }
+                    else {
+                        // Re-add failed chunk to retry
+                        const failedIndex = batch[results.indexOf(result)];
+                        remaining.push(failedIndex);
+                        console.warn(`Chunk ${failedIndex} failed, will retry:`, result.reason);
+                    }
+                }
+            }
+        };
+        await uploadNextBatch();
+    }, [socket, parallelUploads, readChunkAsBase64, updateProgress]);
+    /**
+     * Start a new chunked upload
+     */
+    const upload = useCallback(async (params) => {
+        const { file, title, comments = "", tags = [], collection, documentId } = params;
+        // Validate connection
+        if (connectionState?.status !== "authenticated" &&
+            connectionState?.status !== "unauthenticated") {
+            const error = "Not connected to server";
+            updateProgress({ status: "error", error });
+            onError?.(error);
+            return null;
+        }
+        // Reset state
+        abortControllerRef.current = new AbortController();
+        isPausedRef.current = false;
+        currentFileRef.current = file;
+        const docId = documentId || createDocId();
+        const totalChunks = Math.ceil(file.size / chunkSize);
+        const pendingChunks = Array.from({ length: totalChunks }, (_, i) => i);
+        updateProgress({
+            totalBytes: file.size,
+            bytesUploaded: 0,
+            percentage: 0,
+            totalChunks,
+            chunksUploaded: 0,
+            pendingChunks,
+            status: "preparing",
+            error: undefined,
+            uploadId: undefined,
+            documentId: undefined,
+        });
+        try {
+            // Initialize upload session
+            const metadata = {
+                id: docId,
+                time: Math.floor(Date.now() / 1000),
+                kind: file.type || "application/octet-stream",
+                title,
+                comments,
+                user: "trustgraph", // Will be set by server based on auth
+                collection: collection || "default",
+                tags,
+            };
+            const beginResponse = await socket
+                .librarian()
+                .beginUpload(metadata, file.size, chunkSize);
+            const uploadId = beginResponse["upload-id"];
+            uploadIdRef.current = uploadId;
+            updateProgress({
+                status: "uploading",
+                uploadId,
+            });
+            // Upload all chunks
+            await uploadChunks(file, uploadId, pendingChunks, chunkSize, totalChunks);
+            // Check if cancelled
+            if (abortControllerRef.current?.signal.aborted) {
+                return null;
+            }
+            // Complete the upload
+            updateProgress({ status: "completing" });
+            const completeResponse = await socket.librarian().completeUpload(uploadId);
+            const finalDocId = completeResponse["document-id"];
+            updateProgress({
+                status: "completed",
+                documentId: finalDocId,
+                percentage: 100,
+            });
+            // Invalidate documents cache
+            queryClient.invalidateQueries({ queryKey: ["documents"] });
+            notify.success(`Upload complete: ${title}`);
+            onComplete?.(finalDocId);
+            return finalDocId;
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            updateProgress({ status: "error", error: errorMsg });
+            notify.error(`Upload failed: ${errorMsg}`);
+            onError?.(errorMsg);
+            return null;
+        }
+    }, [
+        socket,
+        connectionState,
+        chunkSize,
+        queryClient,
+        notify,
+        updateProgress,
+        uploadChunks,
+        onComplete,
+        onError,
+    ]);
+    /**
+     * Resume an interrupted upload
+     */
+    const resume = useCallback(async (params) => {
+        const { uploadId, file } = params;
+        // Validate connection
+        if (connectionState?.status !== "authenticated" &&
+            connectionState?.status !== "unauthenticated") {
+            const error = "Not connected to server";
+            updateProgress({ status: "error", error });
+            onError?.(error);
+            return null;
+        }
+        abortControllerRef.current = new AbortController();
+        isPausedRef.current = false;
+        currentFileRef.current = file;
+        uploadIdRef.current = uploadId;
+        updateProgress({
+            status: "preparing",
+            uploadId,
+        });
+        try {
+            // Get current upload status
+            const status = await socket.librarian().getUploadStatus(uploadId);
+            if (status["upload-state"] === "completed") {
+                updateProgress({ status: "completed" });
+                return null;
+            }
+            if (status["upload-state"] === "expired") {
+                throw new Error("Upload session has expired");
+            }
+            const totalChunks = status["total-chunks"];
+            const missingChunks = status["missing-chunks"];
+            const bytesReceived = status["bytes-received"];
+            const totalBytes = status["total-bytes"];
+            updateProgress({
+                totalBytes,
+                bytesUploaded: bytesReceived,
+                percentage: Math.round((bytesReceived / totalBytes) * 100),
+                totalChunks,
+                chunksUploaded: totalChunks - missingChunks.length,
+                pendingChunks: missingChunks,
+                status: "uploading",
+            });
+            // Upload missing chunks
+            const effectiveChunkSize = status["chunk-size"] || chunkSize;
+            await uploadChunks(file, uploadId, missingChunks, effectiveChunkSize, totalChunks);
+            // Check if cancelled
+            if (abortControllerRef.current?.signal.aborted) {
+                return null;
+            }
+            // Complete the upload
+            updateProgress({ status: "completing" });
+            const completeResponse = await socket.librarian().completeUpload(uploadId);
+            const finalDocId = completeResponse["document-id"];
+            updateProgress({
+                status: "completed",
+                documentId: finalDocId,
+                percentage: 100,
+            });
+            // Invalidate documents cache
+            queryClient.invalidateQueries({ queryKey: ["documents"] });
+            notify.success("Upload resumed and completed");
+            onComplete?.(finalDocId);
+            return finalDocId;
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            updateProgress({ status: "error", error: errorMsg });
+            notify.error(`Resume failed: ${errorMsg}`);
+            onError?.(errorMsg);
+            return null;
+        }
+    }, [
+        socket,
+        connectionState,
+        chunkSize,
+        queryClient,
+        notify,
+        updateProgress,
+        uploadChunks,
+        onComplete,
+        onError,
+    ]);
+    /**
+     * Pause the current upload
+     */
+    const pause = useCallback(() => {
+        if (progress.status === "uploading") {
+            isPausedRef.current = true;
+            updateProgress({ status: "paused" });
+        }
+    }, [progress.status, updateProgress]);
+    /**
+     * Resume a paused upload (not to be confused with resuming an interrupted upload)
+     */
+    const unpause = useCallback(() => {
+        if (progress.status === "paused") {
+            isPausedRef.current = false;
+            updateProgress({ status: "uploading" });
+        }
+    }, [progress.status, updateProgress]);
+    /**
+     * Cancel the current upload
+     */
+    const cancel = useCallback(async () => {
+        abortControllerRef.current?.abort();
+        if (uploadIdRef.current) {
+            try {
+                await socket.librarian().abortUpload(uploadIdRef.current);
+            }
+            catch (err) {
+                console.warn("Failed to abort upload on server:", err);
+            }
+        }
+        updateProgress({
+            status: "cancelled",
+            pendingChunks: [],
+        });
+        uploadIdRef.current = null;
+        currentFileRef.current = null;
+    }, [socket, updateProgress]);
+    /**
+     * Reset the upload state to idle
+     */
+    const reset = useCallback(() => {
+        abortControllerRef.current?.abort();
+        uploadIdRef.current = null;
+        currentFileRef.current = null;
+        isPausedRef.current = false;
+        setProgress({
+            totalBytes: 0,
+            bytesUploaded: 0,
+            percentage: 0,
+            totalChunks: 0,
+            chunksUploaded: 0,
+            pendingChunks: [],
+            status: "idle",
+        });
+    }, []);
+    return {
+        // Current progress state
+        progress,
+        // Control methods
+        upload,
+        resume,
+        pause,
+        unpause,
+        cancel,
+        reset,
+        // Convenience flags
+        isIdle: progress.status === "idle",
+        isUploading: progress.status === "uploading",
+        isPaused: progress.status === "paused",
+        isCompleted: progress.status === "completed",
+        isError: progress.status === "error",
+    };
+};
+
+// Default chunk size for downloads: 1MB
+const DEFAULT_CHUNK_SIZE = 1024 * 1024;
+/**
+ * Decode base64 string to Uint8Array
+ */
+const base64ToUint8Array = (base64) => {
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+};
+/**
+ * Trigger browser download of a Blob
+ */
+const triggerBrowserDownload = (blob, filename) => {
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = filename;
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    URL.revokeObjectURL(url);
+};
+/**
+ * Hook for managing streamed document downloads with progress tracking
+ *
+ * Features:
+ * - Streams large documents via WebSocket streaming response
+ * - Progress tracking (chunks received, percentage)
+ * - Cancel support
+ * - Returns Blob or triggers browser download
+ *
+ * @param options - Configuration options for the download
+ * @returns Download state and control methods
+ */
+const useChunkedDownload = (options = {}) => {
+    const { chunkSize = DEFAULT_CHUNK_SIZE, onProgress, onComplete, onError, } = options;
+    const socket = useSocket();
+    const connectionState = useConnectionState();
+    const notify = useNotification();
+    // Download state
+    const [progress, setProgress] = useState({
+        totalChunks: 0,
+        chunksReceived: 0,
+        percentage: 0,
+        status: "idle",
+    });
+    // Refs for managing download lifecycle
+    const cancelledRef = useRef(false);
+    const chunksRef = useRef(new Map());
+    // Update progress and notify callback
+    const updateProgress = useCallback((updates) => {
+        setProgress((prev) => {
+            const next = { ...prev, ...updates };
+            onProgress?.(next);
+            return next;
+        });
+    }, [onProgress]);
+    /**
+     * Download a document via streaming and return as Blob
+     */
+    const download = useCallback((params) => {
+        const { documentId, mimeType = "application/octet-stream", filename } = params;
+        // Validate connection
+        if (connectionState?.status !== "authenticated" &&
+            connectionState?.status !== "unauthenticated") {
+            const error = "Not connected to server";
+            updateProgress({ status: "error", error });
+            onError?.(error);
+            return Promise.resolve(null);
+        }
+        // Reset state
+        cancelledRef.current = false;
+        chunksRef.current = new Map();
+        updateProgress({
+            totalChunks: 0,
+            chunksReceived: 0,
+            percentage: 0,
+            status: "downloading",
+            error: undefined,
+            documentId,
+        });
+        return new Promise((resolve) => {
+            const onChunk = (content, chunkIndex, totalChunks, complete) => {
+                // Check for cancellation
+                if (cancelledRef.current) {
+                    return;
+                }
+                // Store chunk
+                const chunkData = base64ToUint8Array(content);
+                chunksRef.current.set(chunkIndex, chunkData);
+                const chunksReceived = chunksRef.current.size;
+                const percentage = totalChunks > 0
+                    ? Math.round((chunksReceived / totalChunks) * 100)
+                    : 0;
+                updateProgress({
+                    totalChunks,
+                    chunksReceived,
+                    percentage,
+                });
+                // If complete, reassemble and return
+                if (complete) {
+                    if (cancelledRef.current) {
+                        resolve(null);
+                        return;
+                    }
+                    // Reassemble chunks in order
+                    const orderedChunks = [];
+                    for (let i = 0; i < totalChunks; i++) {
+                        const chunk = chunksRef.current.get(i);
+                        if (chunk) {
+                            orderedChunks.push(chunk);
+                        }
+                    }
+                    const blob = new Blob(orderedChunks, { type: mimeType });
+                    updateProgress({
+                        status: "completed",
+                        percentage: 100,
+                        chunksReceived: totalChunks,
+                    });
+                    // Trigger browser download if filename provided
+                    if (filename) {
+                        triggerBrowserDownload(blob, filename);
+                    }
+                    notify.success("Download complete");
+                    onComplete?.(blob, documentId);
+                    resolve(blob);
+                }
+            };
+            const onStreamError = (error) => {
+                if (cancelledRef.current) {
+                    return;
+                }
+                updateProgress({ status: "error", error });
+                notify.error(`Download failed: ${error}`);
+                onError?.(error);
+                resolve(null);
+            };
+            // Start streaming download
+            socket.librarian().streamDocument(documentId, onChunk, onStreamError, chunkSize);
+        });
+    }, [socket, connectionState, chunkSize, notify, updateProgress, onComplete, onError]);
+    /**
+     * Cancel the current download
+     */
+    const cancel = useCallback(() => {
+        cancelledRef.current = true;
+        chunksRef.current = new Map();
+        updateProgress({
+            status: "cancelled",
+        });
+    }, [updateProgress]);
+    /**
+     * Reset the download state to idle
+     */
+    const reset = useCallback(() => {
+        cancelledRef.current = true;
+        chunksRef.current = new Map();
+        setProgress({
+            totalChunks: 0,
+            chunksReceived: 0,
+            percentage: 0,
+            status: "idle",
+        });
+    }, []);
+    return {
+        // Current progress state
+        progress,
+        // Control methods
+        download,
+        cancel,
+        reset,
+        // Convenience flags
+        isIdle: progress.status === "idle",
+        isDownloading: progress.status === "downloading",
+        isCompleted: progress.status === "completed",
+        isError: progress.status === "error",
+    };
+};
+
+/**
+ * Hook for fetching document metadata from the librarian service
+ */
+/**
+ * Hook for fetching a single document's metadata
+ */
+const useDocumentMetadata = (options = {}) => {
+    const { documentId, enabled } = options;
+    const socket = useSocket();
+    const connectionState = useConnectionState();
+    const isSocketReady = connectionState?.status === "authenticated" ||
+        connectionState?.status === "unauthenticated";
+    const query = useQuery({
+        queryKey: ["document-metadata", documentId],
+        enabled: isSocketReady && !!documentId && (enabled !== false),
+        queryFn: async () => {
+            if (!documentId)
+                return null;
+            return socket.librarian().getDocumentMetadata(documentId);
+        },
+    });
+    return {
+        metadata: query.data ?? null,
+        isLoading: query.isLoading,
+        isError: query.isError,
+        error: query.error,
+        refetch: query.refetch,
+    };
+};
+/**
+ * Hook for fetching multiple documents' metadata
+ */
+const useDocumentsMetadata = (documentIds = []) => {
+    const socket = useSocket();
+    const connectionState = useConnectionState();
+    const queryClient = useQueryClient();
+    const isSocketReady = connectionState?.status === "authenticated" ||
+        connectionState?.status === "unauthenticated";
+    const query = useQuery({
+        queryKey: ["documents-metadata", documentIds],
+        enabled: isSocketReady && documentIds.length > 0,
+        queryFn: async () => {
+            const results = await Promise.all(documentIds.map(async (id) => {
+                // Check cache first
+                const cached = queryClient.getQueryData([
+                    "document-metadata",
+                    id,
+                ]);
+                if (cached !== undefined) {
+                    return { id, metadata: cached };
+                }
+                // Fetch and cache
+                const metadata = await socket.librarian().getDocumentMetadata(id);
+                queryClient.setQueryData(["document-metadata", id], metadata);
+                return { id, metadata };
+            }));
+            return results.reduce((acc, { id, metadata }) => {
+                acc[id] = metadata;
+                return acc;
+            }, {});
+        },
+    });
+    return {
+        metadataMap: query.data ?? {},
+        isLoading: query.isLoading,
+        isError: query.isError,
+        error: query.error,
+        refetch: query.refetch,
+    };
+};
+
+export { DEFAULT_SETTINGS, NotificationProvider, RDFS_LABEL, SETTINGS_STORAGE_KEY, createDocId, extractQuotedTriple, fileToBase64, generateFlowBlueprintId, getEventType, getTermValue$1 as getExplainTermValue, getTermValue$3 as getTermValue, getTriples, parseEdgeSelectionTriples, parseExplainTriples, parseExplorationTriples, parseFocusTriples, parseQuestionTriples, parseSynthesisTriples, prepareMetadata, textToBase64, useActivity, useAgentTools, useChat, useChatSession, useChunkedDownload, useChunkedUpload, useCollections, useConversation, useDocumentEmbeddingsQuery, useDocumentMetadata, useDocumentsMetadata, useEmbeddings, useEntityDetail, useExplainability, useExplainabilityStore, useFlowBlueprints, useFlowParameters, useFlows, useGraphEmbeddings, useGraphSubgraph, useInference, useKnowledgeCores, useLLMModels, useLibrary, useLoadStateStore, useMcpTools, useNlpQuery, useNodeDetails, useNotification, useOntologies, useParameterValidation, useProcessing, useProgressStateStore, usePrompts, useProvenance, useRowEmbeddingsQuery, useRowsQuery, useSchemas, useSearchStateStore, useSessionStore, useSettings, useStructuredQuery, useTokenCosts, useTriples, useVectorSearch, useWorkbenchStateStore, vectorSearch };
 //# sourceMappingURL=index.esm.js.map