@trustgraph/react-state 1.5.3 → 1.6.0

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, useRef, useCallback } 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 };
         },
     });
     /**
@@ -1792,10 +1808,45 @@ const useInference = ({ flow } = {}) => {
         },
     });
     /**
-     * Agent inference with streaming callbacks
+     * Document RAG inference with optional explainability
+     */
+    const documentRagMutation = useMutation({
+        mutationFn: async ({ input, collection, docLimit, callbacks, }) => {
+            const wantsExplainability = !!callbacks?.onExplain;
+            const explainEvents = wantsExplainability ? [] : undefined;
+            const response = await new Promise((resolve, reject) => {
+                let accumulated = "";
+                const onChunk = (chunk, complete) => {
+                    accumulated += chunk;
+                    callbacks?.onChunk?.(chunk, complete);
+                    if (complete) {
+                        resolve(accumulated);
+                    }
+                };
+                const onError = (error) => {
+                    callbacks?.onError?.(error);
+                    reject(new Error(error));
+                };
+                const onExplain = wantsExplainability
+                    ? (event) => {
+                        explainEvents.push(event);
+                        callbacks.onExplain(event);
+                    }
+                    : undefined;
+                socket
+                    .flow(effectiveFlow)
+                    .documentRagStreaming(input, onChunk, onError, docLimit, collection, onExplain);
+            });
+            return { response, explainEvents };
+        },
+    });
+    /**
+     * Agent inference with streaming callbacks and optional explainability
      */
     const agentMutation = useMutation({
         mutationFn: async ({ input, callbacks, }) => {
+            const wantsExplainability = !!callbacks?.onExplain;
+            const explainEvents = wantsExplainability ? [] : undefined;
             return new Promise((resolve, reject) => {
                 let fullAnswer = "";
                 const onThink = (thought, complete) => {
@@ -1815,22 +1866,644 @@ const useInference = ({ flow } = {}) => {
                     callbacks?.onError?.(error);
                     reject(new Error(error));
                 };
+                const onExplain = wantsExplainability
+                    ? (event) => {
+                        explainEvents.push(event);
+                        callbacks.onExplain(event);
+                    }
+                    : undefined;
                 socket
                     .flow(effectiveFlow)
-                    .agent(input, onThink, onObserve, onAnswer, onError);
+                    .agent(input, onThink, onObserve, onAnswer, onError, onExplain);
             });
         },
     });
     return {
         graphRag: graphRagMutation.mutateAsync,
+        documentRag: documentRagMutation.mutateAsync,
         textCompletion: textCompletionMutation.mutateAsync,
         agent: agentMutation.mutateAsync,
         isLoading: graphRagMutation.isPending ||
+            documentRagMutation.isPending ||
             textCompletionMutation.isPending ||
             agentMutation.isPending,
     };
 };
 
+/**
+ * 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 +2527,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 +2551,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 +2573,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 +2582,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 +2615,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 +2634,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);
@@ -5187,5 +5903,76 @@ const useChunkedDownload = (options = {}) => {
     };
 };
 
-export { DEFAULT_SETTINGS, NotificationProvider, RDFS_LABEL, SETTINGS_STORAGE_KEY, createDocId, fileToBase64, generateFlowBlueprintId, getTermValue$2 as getTermValue, getTriples, prepareMetadata, textToBase64, useActivity, useAgentTools, useChat, useChatSession, useChunkedDownload, useChunkedUpload, 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 };
+/**
+ * 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