@trustgraph/react-state 1.7.1 → 1.7.2

package/dist/index.cjs

@@ -1922,9 +1922,25 @@ const useExplainabilityStore = zustand.create()((set, get) => ({
 /**
  * Explainability utilities for parsing and structuring explain events
  */
+// Agent-specific predicates (not yet in client library)
+const TG_ACTION = client.TG + "action";
+const TG_ARGUMENTS = client.TG + "arguments";
+const TG_SUBAGENT_GOAL = client.TG + "subagentGoal";
+// RDF type URIs for agent events
+const TG_AGENT_QUESTION = client.TG + "AgentQuestion";
+const TG_ANALYSIS = client.TG + "Analysis";
+const TG_TOOL_USE = client.TG + "ToolUse";
+const TG_OBSERVATION = client.TG + "Observation";
+const TG_THOUGHT_TYPE = client.TG + "Thought";
+const TG_REFLECTION_TYPE = client.TG + "Reflection";
+const TG_CONCLUSION = client.TG + "Conclusion";
+const TG_ANSWER = client.TG + "Answer";
+const TG_FINDING = client.TG + "Finding";
+const TG_SYNTHESIS_TYPE = client.TG + "Synthesis";
+const TG_DECOMPOSITION = client.TG + "Decomposition";
+// ── Helpers ─────────────────────────────────────────────────────────
 /**
- * Extract event type from explainId URI
- * e.g., "urn:trustgraph:question:abc123" → "question"
+ * Extract event type from explainId URI (graph-rag only)
  */
 function getEventType(explainId) {
     if (explainId.includes("question"))
@@ -1969,9 +1985,53 @@ function extractQuotedTriple(term) {
     }
     return null;
 }
+// ── Agent event type detection ──────────────────────────────────────
+/** Map RDF type URI → agent event type (first match wins) */
+const AGENT_TYPE_CHECKS = [
+    [TG_AGENT_QUESTION, "agent-question"],
+    [TG_DECOMPOSITION, "decomposition"],
+    [TG_ANALYSIS, "analysis"],
+    [TG_TOOL_USE, "analysis"],
+    [TG_OBSERVATION, "reflection"],
+    [TG_THOUGHT_TYPE, "reflection"],
+    [TG_REFLECTION_TYPE, "reflection"],
+    [TG_CONCLUSION, "conclusion"],
+    [TG_FINDING, "conclusion"],
+    [TG_SYNTHESIS_TYPE, "conclusion"],
+    [TG_ANSWER, "conclusion"],
+];
 /**
- * Parse triples for a question event
+ * Detect event type from RDF types in embedded triples.
+ * Returns an agent event type if matched, "unknown" otherwise.
  */
+function getEventTypeFromTriples(triples) {
+    const types = new Set();
+    for (const t of triples) {
+        if (getTermValue$1(t.p) === client.RDF_TYPE) {
+            types.add(getTermValue$1(t.o));
+        }
+    }
+    for (const [typeUri, eventType] of AGENT_TYPE_CHECKS) {
+        if (types.has(typeUri))
+            return eventType;
+    }
+    return "unknown";
+}
+/** Extract common fields (label, derivedFrom) from triples */
+function extractCommonFields(triples) {
+    const derivedFrom = [];
+    let label;
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === client.RDFS_LABEL && o)
+            label = o;
+        if (p === client.PROV_WAS_DERIVED_FROM && o)
+            derivedFrom.push(o);
+    }
+    return { label, derivedFrom };
+}
+// ── Graph-RAG parsers (existing) ────────────────────────────────────
 function parseQuestionTriples(explainId, explainGraph, triples) {
     const event = {
         type: "question",
@@ -1990,9 +2050,6 @@ function parseQuestionTriples(explainId, explainGraph, triples) {
     }
     return event;
 }
-/**
- * Parse triples for an exploration event
- */
 function parseExplorationTriples(explainId, explainGraph, triples) {
     const event = {
         type: "exploration",
@@ -2008,9 +2065,6 @@ function parseExplorationTriples(explainId, explainGraph, triples) {
     }
     return event;
 }
-/**
- * Parse triples for a focus event
- */
 function parseFocusTriples(explainId, explainGraph, triples) {
     const event = {
         type: "focus",
@@ -2027,9 +2081,6 @@ function parseFocusTriples(explainId, explainGraph, triples) {
     }
     return event;
 }
-/**
- * Parse triples for a synthesis event
- */
 function parseSynthesisTriples(explainId, explainGraph, triples) {
     const event = {
         type: "synthesis",
@@ -2045,9 +2096,6 @@ function parseSynthesisTriples(explainId, explainGraph, triples) {
     }
     return event;
 }
-/**
- * Parse triples for an edge selection entity
- */
 function parseEdgeSelectionTriples(triples) {
     let edge = null;
     let reasoning = null;
@@ -2062,10 +2110,109 @@ function parseEdgeSelectionTriples(triples) {
     }
     return { edge, reasoning };
 }
+// ── Agent parsers (new) ─────────────────────────────────────────────
+function parseAgentQuestionTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    const event = {
+        type: "agent-question",
+        explainId,
+        explainGraph,
+        label,
+        derivedFrom,
+    };
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === client.TG_QUERY)
+            event.query = o;
+        if (p === client.PROV_STARTED_AT_TIME)
+            event.timestamp = o;
+    }
+    return event;
+}
+function parseDecompositionTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    const goals = [];
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === TG_SUBAGENT_GOAL && o)
+            goals.push(o);
+    }
+    return {
+        type: "decomposition",
+        explainId,
+        explainGraph,
+        label,
+        goals,
+        derivedFrom,
+    };
+}
+function parseAnalysisTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    const event = {
+        type: "analysis",
+        explainId,
+        explainGraph,
+        label,
+        derivedFrom,
+    };
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === TG_ACTION)
+            event.action = o;
+        if (p === TG_ARGUMENTS)
+            event.arguments = o;
+    }
+    return event;
+}
+function parseReflectionTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    return {
+        type: "reflection",
+        explainId,
+        explainGraph,
+        label,
+        derivedFrom,
+    };
+}
+function parseConclusionTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    return {
+        type: "conclusion",
+        explainId,
+        explainGraph,
+        label,
+        derivedFrom,
+    };
+}
+// ── Unified parser ──────────────────────────────────────────────────
 /**
- * Parse triples based on event type
+ * Parse triples into a structured event.
+ * Tries RDF type detection first (agent events), then URI patterns (graph-rag).
+ * Returns null for events with no triples (inner graph-rag plumbing).
  */
 function parseExplainTriples(explainId, explainGraph, triples) {
+    if (triples.length === 0)
+        return null;
+    // Try RDF type detection first (agent events with embedded triples)
+    const rdfEventType = getEventTypeFromTriples(triples);
+    if (rdfEventType !== "unknown") {
+        switch (rdfEventType) {
+            case "agent-question":
+                return parseAgentQuestionTriples(explainId, explainGraph, triples);
+            case "decomposition":
+                return parseDecompositionTriples(explainId, explainGraph, triples);
+            case "analysis":
+                return parseAnalysisTriples(explainId, explainGraph, triples);
+            case "reflection":
+                return parseReflectionTriples(explainId, explainGraph, triples);
+            case "conclusion":
+                return parseConclusionTriples(explainId, explainGraph, triples);
+        }
+    }
+    // Fall back to URI pattern detection (graph-rag events)
     const eventType = getEventType(explainId);
     switch (eventType) {
         case "question":
@@ -2252,24 +2399,26 @@ const useProvenance = (options = {}) => {
  *
  * 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
+ * - Explain triples are embedded directly in events (no store lookups)
+ * - Edge labels are resolved via triple store queries
+ * - Edge label resolution + provenance runs in parallel
+ * - onUpdate callback fires on every session state change, allowing
+ *   callers to sync to external stores (e.g. Zustand)
  */
 /**
  * Hook for managing explainability during inference
  */
 const useExplainability = (options = {}) => {
     const { flow, collection = "default", traceProvenance = true, } = options;
-    const socket = reactProvider.useSocket();
-    const connectionState = reactProvider.useConnectionState();
     const sessionFlowId = useSessionStore((state) => state.flowId);
     const effectiveFlow = flow ?? sessionFlowId;
     const { traceEdgeProvenance, resolveLabel } = useProvenance({
         flow: effectiveFlow,
         collection,
     });
+    // Keep onUpdate in a ref so it doesn't break memoisation
+    const onUpdateRef = react.useRef(options.onUpdate);
+    onUpdateRef.current = options.onUpdate;
     const [events, setEvents] = react.useState([]);
     const [session, setSession] = react.useState({});
     const [isUnpacking, setIsUnpacking] = react.useState(false);
@@ -2280,98 +2429,19 @@ const useExplainability = (options = {}) => {
     const unpackQueueRef = react.useRef([]);
     const isProcessingRef = react.useRef(false);
     /**
-     * Check if connected
-     */
-    const isConnected = react.useCallback(() => {
-        return (connectionState?.status === "authenticated" ||
-            connectionState?.status === "unauthenticated");
-    }, [connectionState]);
-    /**
-     * Single triple query (no retry)
-     */
-    const fetchTriples = react.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 = react.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 = react.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
+     * Resolve a single edge: extract from embedded triples, resolve labels
      */
-    const resolveEdge = react.useCallback(async (edgeSelUri, explainGraph) => {
-        const triples = await queryWithSimpleRetry(edgeSelUri, explainGraph);
-        const { edge, reasoning } = parseEdgeSelectionTriples(triples);
+    const resolveEdge = react.useCallback(async (edgeSelUri, allTriples) => {
+        // Filter embedded triples for this edge selection URI
+        const edgeTriples = allTriples.filter((t) => getTermValue$1(t.s) === edgeSelUri);
+        const { edge, reasoning } = parseEdgeSelectionTriples(edgeTriples);
         if (!edge)
             return null;
         const selectedEdge = {
             edge,
             reasoning: reasoning || undefined,
         };
-        // Kick off labels and provenance in parallel
+        // Kick off label resolution and provenance in parallel
         const [labels, provenanceChains] = await Promise.all([
             // Labels — all 3 in parallel
             Promise.all([
@@ -2389,13 +2459,13 @@ const useExplainability = (options = {}) => {
             selectedEdge.sources = provenanceChains.map((c) => c.chain).flat();
         }
         return selectedEdge;
-    }, [queryWithSimpleRetry, resolveLabel, traceProvenance, traceEdgeProvenance]);
+    }, [resolveLabel, traceProvenance, traceEdgeProvenance]);
     /**
      * Unpack a focus event — resolve ALL edges in parallel
      */
-    const unpackFocusEvent = react.useCallback(async (focusEvent) => {
+    const unpackFocusEvent = react.useCallback(async (focusEvent, allTriples) => {
         // Fire off all edge resolutions concurrently
-        const edgePromises = focusEvent.edgeSelectionUris.map((uri) => resolveEdge(uri, focusEvent.explainGraph));
+        const edgePromises = focusEvent.edgeSelectionUris.map((uri) => resolveEdge(uri, allTriples));
         const results = await Promise.all(edgePromises);
         const selectedEdges = results.filter((e) => e !== null);
         return {
@@ -2403,50 +2473,62 @@ const useExplainability = (options = {}) => {
             selectedEdges,
         };
     }, [resolveEdge]);
-    /** Helper to update both state and ref together */
+    /** Helper to update state, ref, and notify caller together */
     const updateSession = react.useCallback((updater) => {
         sessionRef.current = updater(sessionRef.current);
         setSession(updater);
+        onUpdateRef.current?.(sessionRef.current);
     }, []);
+    const AGENT_EVENT_TYPES = new Set([
+        "agent-question", "decomposition", "analysis", "reflection", "conclusion",
+    ]);
     /**
      * Process a single explain event
      */
     const processEvent = react.useCallback(async (event) => {
-        // Query triples for main event node (stability retry)
-        const triples = await queryWithStabilityRetry(event.explainId, event.explainGraph);
+        // Use embedded triples directly from the event
+        const triples = event.explainTriples ?? [];
         // 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);
+        if (AGENT_EVENT_TYPES.has(parsed.type)) {
+            // Agent event — append to timeline
             updateSession((prev) => ({
                 ...prev,
-                focus: unpackedFocus,
+                agentSteps: [...(prev.agentSteps || []), parsed],
             }));
         }
-    }, [queryWithStabilityRetry, unpackFocusEvent, updateSession]);
+        else {
+            // Graph-RAG event — populate fixed fields
+            updateSession((prev) => {
+                const next = { ...prev };
+                switch (parsed.type) {
+                    case "question":
+                        next.question = parsed;
+                        break;
+                    case "exploration":
+                        next.exploration = parsed;
+                        break;
+                    case "focus":
+                        next.focus = parsed;
+                        break;
+                    case "synthesis":
+                        next.synthesis = parsed;
+                        break;
+                }
+                return next;
+            });
+            // For focus events, unpack edges (labels still need store lookup)
+            if (parsed.type === "focus") {
+                const unpackedFocus = await unpackFocusEvent(parsed, triples);
+                updateSession((prev) => ({
+                    ...prev,
+                    focus: unpackedFocus,
+                }));
+            }
+        }
+    }, [unpackFocusEvent, updateSession]);
     /**
      * Process the unpack queue
      */
@@ -2529,10 +2611,18 @@ const useChatSession = ({ flow } = {}) => {
     const { settings } = useSettings();
     // Explainability store for persisting sessions
     const addExplainSession = useExplainabilityStore((state) => state.addSession);
-    // Explainability hook for processing events (processes each event immediately)
+    // Track the current explain session ID so onUpdate can target the right store key
+    const explainSessionIdRef = react.useRef(undefined);
+    // Explainability hook — onUpdate syncs every state change to the Zustand store
     const explainability = useExplainability({
         flow: effectiveFlow,
         collection: settings.collection,
+        onUpdate: (session) => {
+            const id = explainSessionIdRef.current;
+            if (id) {
+                addExplainSession(id, session);
+            }
+        },
     });
     const explainabilityRef = react.useRef(explainability);
     explainabilityRef.current = explainability;
@@ -2551,13 +2641,9 @@ 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();
-        }
+        const sessionId = generateSessionId();
+        explainabilityRef.current.reset();
+        explainSessionIdRef.current = sessionId;
         try {
             // Execute Graph RAG with streaming and entity discovery
             const result = await inference.graphRag({
@@ -2573,41 +2659,20 @@ const useChatSession = ({ flow } = {}) => {
                     onChunk: (chunk, complete) => {
                         accumulated += chunk;
                         if (!messageAdded) {
-                            // Add empty message on first chunk (with session ID if enabled)
                             addMessage("ai", accumulated, undefined, sessionId);
                             messageAdded = true;
                         }
                         else {
-                            // Update existing message with accumulated text
                             updateLastMessage(accumulated);
                         }
                     },
-                    // Wire up explainability callback if feature is enabled
-                    ...(explainabilityEnabled && {
-                        onExplain: (event) => {
-                            console.log("[explain] event received:", event.explainId);
-                            explainabilityRef.current.addEvent(event);
-                        },
-                    }),
+                    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
@@ -2695,9 +2760,13 @@ const useChatSession = ({ flow } = {}) => {
         let observationMessageAdded = false;
         let answerAccumulated = "";
         let answerMessageAdded = false;
+        const sessionId = generateSessionId();
+        explainabilityRef.current.reset();
+        explainSessionIdRef.current = sessionId;
         try {
             const response = await inference.agent({
                 input,
+                collection: settings.collection,
                 callbacks: {
                     onThink: (thought, complete) => {
                         thinkingAccumulated += thought;
@@ -2730,13 +2799,17 @@ const useChatSession = ({ flow } = {}) => {
                     onAnswer: (answer, complete) => {
                         answerAccumulated += answer;
                         if (!answerMessageAdded) {
-                            addMessage("ai", answerAccumulated, "answer");
+                            addMessage("ai", answerAccumulated, "answer", sessionId);
                             answerMessageAdded = true;
                         }
                         else {
                             updateLastMessage(answerAccumulated);
                         }
                     },
+                    onExplain: (event) => {
+                        console.log("[explain] agent event received:", event.explainId);
+                        explainabilityRef.current.addEvent(event);
+                    },
                 },
             });
             removeActivity(activity);
@@ -6093,6 +6166,7 @@ exports.extractQuotedTriple = extractQuotedTriple;
 exports.fileToBase64 = fileToBase64;
 exports.generateFlowBlueprintId = generateFlowBlueprintId;
 exports.getEventType = getEventType;
+exports.getEventTypeFromTriples = getEventTypeFromTriples;
 exports.getExplainTermValue = getTermValue$1;
 exports.getTermValue = getTermValue$3;
 exports.getTriples = getTriples;