@trustgraph/react-state 1.7.2 → 1.7.3

package/dist/index.cjs

@@ -1922,11 +1922,13 @@ const useExplainabilityStore = zustand.create()((set, get) => ({
 /**
  * Explainability utilities for parsing and structuring explain events
  */
-// Agent-specific predicates (not yet in client library)
+// 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_CONCEPT = client.TG + "concept";
+const TG_ENTITY = client.TG + "entity";
+// RDF type URIs
 const TG_AGENT_QUESTION = client.TG + "AgentQuestion";
 const TG_ANALYSIS = client.TG + "Analysis";
 const TG_TOOL_USE = client.TG + "ToolUse";
@@ -1934,13 +1936,14 @@ 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";
+const TG_GROUNDING = client.TG + "Grounding";
+const TG_EXPLORATION_TYPE = client.TG + "Exploration";
+const TG_FOCUS_TYPE = client.TG + "Focus";
 // ── Helpers ─────────────────────────────────────────────────────────
 /**
- * Extract event type from explainId URI (graph-rag only)
+ * Extract event type from explainId URI (graph-rag fallback)
  */
 function getEventType(explainId) {
     if (explainId.includes("question"))
@@ -1953,9 +1956,6 @@ function getEventType(explainId) {
         return "synthesis";
     return "unknown";
 }
-/**
- * Get term value from a Term object
- */
 function getTermValue$1(term) {
     if (!term)
         return "";
@@ -1964,7 +1964,6 @@ function getTermValue$1(term) {
     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);
@@ -1972,9 +1971,6 @@ function getTermValue$1(term) {
     }
     return "";
 }
-/**
- * Extract quoted triple from a Term
- */
 function extractQuotedTriple(term) {
     if (term.t === "t" && term.tr) {
         return {
@@ -1985,9 +1981,15 @@ function extractQuotedTriple(term) {
     }
     return null;
 }
-// ── Agent event type detection ──────────────────────────────────────
-/** Map RDF type URI → agent event type (first match wins) */
-const AGENT_TYPE_CHECKS = [
+// ── RDF type detection ──────────────────────────────────────────────
+/**
+ * Map RDF type URI → event type (first match wins).
+ * Agent-specific types only — shared types like tg:Synthesis and
+ * tg:Answer are excluded to avoid catching graph-rag events.
+ * Grounding, Exploration, Focus are included since they now carry
+ * embedded triples with their RDF type.
+ */
+const RDF_TYPE_CHECKS = [
     [TG_AGENT_QUESTION, "agent-question"],
     [TG_DECOMPOSITION, "decomposition"],
     [TG_ANALYSIS, "analysis"],
@@ -1997,12 +1999,12 @@ const AGENT_TYPE_CHECKS = [
     [TG_REFLECTION_TYPE, "reflection"],
     [TG_CONCLUSION, "conclusion"],
     [TG_FINDING, "conclusion"],
-    [TG_SYNTHESIS_TYPE, "conclusion"],
-    [TG_ANSWER, "conclusion"],
+    [TG_GROUNDING, "grounding"],
+    [TG_EXPLORATION_TYPE, "exploration"],
+    [TG_FOCUS_TYPE, "focus"],
 ];
 /**
  * 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();
@@ -2011,7 +2013,7 @@ function getEventTypeFromTriples(triples) {
             types.add(getTermValue$1(t.o));
         }
     }
-    for (const [typeUri, eventType] of AGENT_TYPE_CHECKS) {
+    for (const [typeUri, eventType] of RDF_TYPE_CHECKS) {
         if (types.has(typeUri))
             return eventType;
     }
@@ -2031,38 +2033,48 @@ function extractCommonFields(triples) {
     }
     return { label, derivedFrom };
 }
-// ── Graph-RAG parsers (existing) ────────────────────────────────────
+/**
+ * Extract inline edges from triples (tg:edge quoted triples).
+ * Returns SelectedEdge objects with URIs — labels resolved later.
+ */
+function extractInlineEdges(triples) {
+    const edges = [];
+    for (const t of triples) {
+        if (getTermValue$1(t.p) === client.TG_EDGE && t.o.t === "t" && t.o.tr) {
+            const edge = extractQuotedTriple(t.o);
+            if (edge) {
+                edges.push({ edge });
+            }
+        }
+    }
+    return edges;
+}
+// ── Parsers ─────────────────────────────────────────────────────────
 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 === client.TG_QUERY) {
+    const event = { type: "question", explainId, explainGraph };
+    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;
-        }
-        else if (p === client.PROV_STARTED_AT_TIME) {
+        else if (p === client.PROV_STARTED_AT_TIME)
             event.timestamp = o;
-        }
     }
     return 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 === client.TG_EDGE_COUNT) {
+    const event = { type: "exploration", explainId, explainGraph };
+    const entities = [];
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === client.TG_EDGE_COUNT)
             event.edgeCount = parseInt(o, 10);
-        }
+        if (p === TG_ENTITY && o)
+            entities.push(o);
     }
+    if (entities.length > 0)
+        event.entities = entities;
     return event;
 }
 function parseFocusTriples(explainId, explainGraph, triples) {
@@ -2072,27 +2084,28 @@ function parseFocusTriples(explainId, explainGraph, triples) {
         explainGraph,
         edgeSelectionUris: [],
     };
-    for (const triple of triples) {
-        const p = getTermValue$1(triple.p);
-        const o = getTermValue$1(triple.o);
+    // Collect edge selection URIs (old format)
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
         if (p === client.TG_SELECTED_EDGE && typeof o === "string") {
             event.edgeSelectionUris.push(o);
         }
     }
+    // Extract inline edges (new format: tg:edge with quoted triples)
+    const inlineEdges = extractInlineEdges(triples);
+    if (inlineEdges.length > 0) {
+        event.selectedEdges = inlineEdges;
+    }
     return 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 === client.TG_CONTENT) {
+    const event = { type: "synthesis", explainId, explainGraph };
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === client.TG_CONTENT)
             event.contentLength = o.length;
-        }
     }
     return event;
 }
@@ -2101,24 +2114,28 @@ function parseEdgeSelectionTriples(triples) {
     let reasoning = null;
     for (const triple of triples) {
         const p = getTermValue$1(triple.p);
-        if (p === client.TG_EDGE) {
+        if (p === client.TG_EDGE)
             edge = extractQuotedTriple(triple.o);
-        }
-        else if (p === client.TG_REASONING) {
+        else if (p === client.TG_REASONING)
             reasoning = getTermValue$1(triple.o);
-        }
     }
     return { edge, reasoning };
 }
-// ── Agent parsers (new) ─────────────────────────────────────────────
+function parseGroundingTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    const concepts = [];
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === TG_CONCEPT && o)
+            concepts.push(o);
+    }
+    return { type: "grounding", explainId, explainGraph, label, concepts, derivedFrom };
+}
 function parseAgentQuestionTriples(explainId, explainGraph, triples) {
     const { label, derivedFrom } = extractCommonFields(triples);
     const event = {
-        type: "agent-question",
-        explainId,
-        explainGraph,
-        label,
-        derivedFrom,
+        type: "agent-question", explainId, explainGraph, label, derivedFrom,
     };
     for (const t of triples) {
         const p = getTermValue$1(t.p);
@@ -2139,23 +2156,12 @@ function parseDecompositionTriples(explainId, explainGraph, triples) {
         if (p === TG_SUBAGENT_GOAL && o)
             goals.push(o);
     }
-    return {
-        type: "decomposition",
-        explainId,
-        explainGraph,
-        label,
-        goals,
-        derivedFrom,
-    };
+    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,
+        type: "analysis", explainId, explainGraph, label, derivedFrom,
     };
     for (const t of triples) {
         const p = getTermValue$1(t.p);
@@ -2169,34 +2175,22 @@ function parseAnalysisTriples(explainId, explainGraph, triples) {
 }
 function parseReflectionTriples(explainId, explainGraph, triples) {
     const { label, derivedFrom } = extractCommonFields(triples);
-    return {
-        type: "reflection",
-        explainId,
-        explainGraph,
-        label,
-        derivedFrom,
-    };
+    return { type: "reflection", explainId, explainGraph, label, derivedFrom };
 }
 function parseConclusionTriples(explainId, explainGraph, triples) {
     const { label, derivedFrom } = extractCommonFields(triples);
-    return {
-        type: "conclusion",
-        explainId,
-        explainGraph,
-        label,
-        derivedFrom,
-    };
+    return { type: "conclusion", explainId, explainGraph, label, derivedFrom };
 }
 // ── Unified parser ──────────────────────────────────────────────────
 /**
  * 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).
+ * Tries RDF type detection first, then URI patterns as fallback.
+ * Returns null for events with no triples.
  */
 function parseExplainTriples(explainId, explainGraph, triples) {
     if (triples.length === 0)
         return null;
-    // Try RDF type detection first (agent events with embedded triples)
+    // Try RDF type detection first
     const rdfEventType = getEventTypeFromTriples(triples);
     if (rdfEventType !== "unknown") {
         switch (rdfEventType) {
@@ -2210,6 +2204,12 @@ function parseExplainTriples(explainId, explainGraph, triples) {
                 return parseReflectionTriples(explainId, explainGraph, triples);
             case "conclusion":
                 return parseConclusionTriples(explainId, explainGraph, triples);
+            case "grounding":
+                return parseGroundingTriples(explainId, explainGraph, triples);
+            case "exploration":
+                return parseExplorationTriples(explainId, explainGraph, triples);
+            case "focus":
+                return parseFocusTriples(explainId, explainGraph, triples);
         }
     }
     // Fall back to URI pattern detection (graph-rag events)
@@ -2230,8 +2230,10 @@ function parseExplainTriples(explainId, explainGraph, triples) {
 
 /**
  * Hook for tracing provenance chains in the knowledge graph
- * Follows prov:wasDerivedFrom relationships from any entity to its source documents
+ * Follows tg:contains to find subgraphs, then prov:wasDerivedFrom
+ * to trace chunk → page → document chains
  */
+const TG_CONTAINS = client.TG + "contains";
 /**
  * Hook for tracing provenance chains
  */
@@ -2328,13 +2330,13 @@ const useProvenance = (options = {}) => {
         }
     }, [maxDepth, resolveLabel, queryDerivedFrom]);
     /**
-     * Query for statements that reify an edge via tg:reifies
+     * Find subgraphs that contain an edge via tg:contains with a quoted triple
      */
-    const queryReifyingStatements = react.useCallback(async (s, p, o) => {
+    const queryContainingSubgraphs = react.useCallback(async (s, p, o) => {
         if (!isConnected())
             return [];
         try {
-            // Build the quoted triple term
+            // Build the quoted triple term for the edge
             const quotedTriple = {
                 t: "t",
                 tr: {
@@ -2347,7 +2349,7 @@ const useProvenance = (options = {}) => {
             };
             const triples = await socket
                 .flow(effectiveFlow)
-                .triplesQuery(undefined, { t: "i", i: client.TG_REIFIES }, quotedTriple, 10, collection);
+                .triplesQuery(undefined, { t: "i", i: TG_CONTAINS }, quotedTriple, 10, collection);
             return triples.map((t) => getTermValue$1(t.s));
         }
         catch {
@@ -2355,20 +2357,21 @@ const useProvenance = (options = {}) => {
         }
     }, [socket, effectiveFlow, collection, isConnected]);
     /**
-     * Trace provenance for an edge - finds reifying statements and traces each
+     * Trace provenance for an edge — find containing subgraph, then follow
+     * wasDerivedFrom chain: subgraph → chunk → page → document
      */
     const traceEdgeProvenance = react.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
+            // Find subgraphs containing this edge
+            const subgraphUris = await queryContainingSubgraphs(s, p, o);
             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);
+            for (const subgraphUri of subgraphUris) {
+                // Follow wasDerivedFrom from the subgraph to the chunk
+                const chunkUri = await queryDerivedFrom(subgraphUri);
+                if (chunkUri) {
+                    // Trace the full chain from chunk upward
+                    const chain = await traceChain(chunkUri);
                     chains.push(chain);
                 }
             }
@@ -2377,7 +2380,7 @@ const useProvenance = (options = {}) => {
         finally {
             setIsTracing(false);
         }
-    }, [queryReifyingStatements, queryDerivedFrom, traceChain]);
+    }, [queryContainingSubgraphs, queryDerivedFrom, traceChain]);
     /**
      * Clear the label cache
      */
@@ -2479,56 +2482,82 @@ const useExplainability = (options = {}) => {
         setSession(updater);
         onUpdateRef.current?.(sessionRef.current);
     }, []);
-    const AGENT_EVENT_TYPES = new Set([
+    const AGENT_STEP_TYPES = new Set([
         "agent-question", "decomposition", "analysis", "reflection", "conclusion",
+        "grounding",
     ]);
+    /**
+     * Resolve labels for inline edges (edges already extracted, just need labels)
+     */
+    const resolveEdgeLabels = react.useCallback(async (focusEvent) => {
+        if (!focusEvent.selectedEdges || focusEvent.selectedEdges.length === 0) {
+            return focusEvent;
+        }
+        const resolved = await Promise.all(focusEvent.selectedEdges.map(async (se) => {
+            const [sLabel, pLabel, oLabel] = await Promise.all([
+                resolveLabel(se.edge.s),
+                resolveLabel(se.edge.p),
+                resolveLabel(se.edge.o),
+            ]);
+            let sources;
+            if (traceProvenance) {
+                const chains = await traceEdgeProvenance(se.edge.s, se.edge.p, se.edge.o);
+                if (chains.length > 0) {
+                    sources = chains.map((c) => c.chain).flat();
+                }
+            }
+            return {
+                ...se,
+                labels: { s: sLabel, p: pLabel, o: oLabel },
+                sources,
+            };
+        }));
+        return { ...focusEvent, selectedEdges: resolved };
+    }, [resolveLabel, traceProvenance, traceEdgeProvenance]);
     /**
      * Process a single explain event
      */
     const processEvent = react.useCallback(async (event) => {
-        // 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;
-        if (AGENT_EVENT_TYPES.has(parsed.type)) {
-            // Agent event — append to timeline
+        if (AGENT_STEP_TYPES.has(parsed.type)) {
+            // Agent step — append to timeline
             updateSession((prev) => ({
                 ...prev,
                 agentSteps: [...(prev.agentSteps || []), parsed],
             }));
         }
-        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;
+        // Graph-RAG fields — populate regardless (agent produces these too)
+        switch (parsed.type) {
+            case "question":
+                updateSession((prev) => ({ ...prev, question: parsed }));
+                break;
+            case "exploration":
+                updateSession((prev) => ({ ...prev, exploration: parsed }));
+                break;
+            case "focus": {
+                updateSession((prev) => ({ ...prev, focus: parsed }));
+                // Resolve labels for inline edges, or unpack old-format edges
+                const focusEvent = parsed;
+                if (focusEvent.selectedEdges && focusEvent.selectedEdges.length > 0) {
+                    // New format: edges already extracted, resolve labels
+                    const resolved = await resolveEdgeLabels(focusEvent);
+                    updateSession((prev) => ({ ...prev, focus: resolved }));
                 }
-                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,
-                }));
+                else if (focusEvent.edgeSelectionUris.length > 0) {
+                    // Old format: unpack edge selection URIs
+                    const unpacked = await unpackFocusEvent(focusEvent, triples);
+                    updateSession((prev) => ({ ...prev, focus: unpacked }));
+                }
+                break;
             }
+            case "synthesis":
+                updateSession((prev) => ({ ...prev, synthesis: parsed }));
+                break;
         }
-    }, [unpackFocusEvent, updateSession]);
+    }, [unpackFocusEvent, resolveEdgeLabels, updateSession]);
     /**
      * Process the unpack queue
      */