@trustgraph/react-state 1.5.3 → 1.5.4

package/dist/model/message.d.ts

@@ -2,5 +2,6 @@ export interface Message {
     role: string;
     text: string;
     type?: "normal" | "thinking" | "observation" | "answer";
+    explainSessionId?: string;
 }
 //# sourceMappingURL=message.d.ts.map

package/dist/model/message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../src/model/message.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,QAAQ,CAAC;CACzD"}
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../src/model/message.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,QAAQ,CAAC;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B"}

package/dist/model/settings-types.d.ts

@@ -21,6 +21,7 @@ export interface Settings {
         flowBlueprintEditor: boolean;
         structuredQuery: boolean;
         llmModels: boolean;
+        explainability: boolean;
     };
 }
 export declare const DEFAULT_SETTINGS: Settings;

package/dist/model/settings-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings-types.d.ts","sourceRoot":"","sources":["../../src/model/settings-types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,EAAE;QACR,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,eAAe,EAAE;QACf,cAAc,EAAE,OAAO,CAAC;QACxB,WAAW,EAAE,OAAO,CAAC;QACrB,UAAU,EAAE,OAAO,CAAC;QACpB,QAAQ,EAAE,OAAO,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,SAAS,EAAE,OAAO,CAAC;QACnB,cAAc,EAAE,OAAO,CAAC;QACxB,mBAAmB,EAAE,OAAO,CAAC;QAC7B,eAAe,EAAE,OAAO,CAAC;QACzB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC;CACH;AAED,eAAO,MAAM,gBAAgB,EAAE,QAwB9B,CAAC;AAEF,eAAO,MAAM,oBAAoB,wBAAwB,CAAC"}
+{"version":3,"file":"settings-types.d.ts","sourceRoot":"","sources":["../../src/model/settings-types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,EAAE;QACR,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,eAAe,EAAE;QACf,cAAc,EAAE,OAAO,CAAC;QACxB,WAAW,EAAE,OAAO,CAAC;QACrB,UAAU,EAAE,OAAO,CAAC;QACpB,QAAQ,EAAE,OAAO,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,SAAS,EAAE,OAAO,CAAC;QACnB,cAAc,EAAE,OAAO,CAAC;QACxB,mBAAmB,EAAE,OAAO,CAAC;QAC7B,eAAe,EAAE,OAAO,CAAC;QACzB,SAAS,EAAE,OAAO,CAAC;QACnB,cAAc,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAED,eAAO,MAAM,gBAAgB,EAAE,QAyB9B,CAAC;AAEF,eAAO,MAAM,oBAAoB,wBAAwB,CAAC"}

package/dist/state/chat-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat-session.d.ts","sourceRoot":"","sources":["../../src/state/chat-session.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,WAAU;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO;;eAuOpB,MAAM;;;;CAoDhD,CAAC;AAGF,eAAO,MAAM,OAAO,cA9RqB;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE;;eAuOf,MAAM;;;;CAuDZ,CAAC"}
+{"version":3,"file":"chat-session.d.ts","sourceRoot":"","sources":["../../src/state/chat-session.ts"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,WAAU;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO;;eAwRpB,MAAM;;;;CAoDhD,CAAC;AAGF,eAAO,MAAM,OAAO,cA/UqB;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE;;eAwRf,MAAM;;;;CAuDZ,CAAC"}

package/dist/state/conversation.d.ts

@@ -5,8 +5,8 @@ export interface ConversationState {
     input: string;
     chatMode: ChatMode;
     setMessages: (v: Message[]) => void;
-    addMessage: (role: string, text: string, type?: "normal" | "thinking" | "observation" | "answer") => void;
-    updateLastMessage: (text: string) => void;
+    addMessage: (role: string, text: string, type?: "normal" | "thinking" | "observation" | "answer", explainSessionId?: string) => void;
+    updateLastMessage: (text: string, explainSessionId?: string) => void;
     setInput: (v: string) => void;
     setChatMode: (mode: ChatMode) => void;
 }

package/dist/state/conversation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../../src/state/conversation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IAEnB,WAAW,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC,UAAU,EAAE,CACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,QAAQ,KACpD,IAAI,CAAC;IACV,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;CACvC;AAED,eAAO,MAAM,eAAe,gFAgDzB,CAAC"}
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../../src/state/conversation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IAEnB,WAAW,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC,UAAU,EAAE,CACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,QAAQ,EACvD,gBAAgB,CAAC,EAAE,MAAM,KACtB,IAAI,CAAC;IACV,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;CACvC;AAED,eAAO,MAAM,eAAe,gFAmDzB,CAAC"}

package/dist/state/document-metadata.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Hook for fetching document metadata from the librarian service
+ */
+import type { DocumentMetadata } from "@trustgraph/client";
+export interface UseDocumentMetadataOptions {
+    /** Document ID to fetch */
+    documentId?: string;
+    /** Whether to enable the query (default: true if documentId is provided) */
+    enabled?: boolean;
+}
+export interface UseDocumentMetadataResult {
+    /** Document metadata if loaded */
+    metadata: DocumentMetadata | null;
+    /** Whether the query is loading */
+    isLoading: boolean;
+    /** Whether there was an error */
+    isError: boolean;
+    /** Error object if any */
+    error: Error | null;
+    /** Refetch the metadata */
+    refetch: () => void;
+}
+/**
+ * Hook for fetching a single document's metadata
+ */
+export declare const useDocumentMetadata: (options?: UseDocumentMetadataOptions) => UseDocumentMetadataResult;
+/**
+ * Hook for fetching multiple documents' metadata
+ */
+export declare const useDocumentsMetadata: (documentIds?: string[]) => {
+    metadataMap: Record<string, DocumentMetadata>;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<Record<string, DocumentMetadata>, Error>>;
+};
+//# sourceMappingURL=document-metadata.d.ts.map

package/dist/state/document-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-metadata.d.ts","sourceRoot":"","sources":["../../src/state/document-metadata.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,0BAA0B;IACzC,2BAA2B;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,kCAAkC;IAClC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAClC,mCAAmC;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,iCAAiC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,0BAA0B;IAC1B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC9B,UAAS,0BAA+B,KACvC,yBA0BF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,cAAa,MAAM,EAAO;;;;;;CAgD9D,CAAC"}

package/dist/state/explainability-store.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Zustand store for managing explainability sessions
+ * Sessions are keyed by ID and linked to messages via explainSessionId
+ */
+import type { ExplainabilitySession } from "../utils/explainability";
+export interface ExplainabilityStoreState {
+    /** Map of session ID to session data */
+    sessions: Record<string, ExplainabilitySession>;
+    /** Add or update a session */
+    addSession: (id: string, session: ExplainabilitySession) => void;
+    /** Update an existing session (merges with existing data) */
+    updateSession: (id: string, partial: Partial<ExplainabilitySession>) => void;
+    /** Get a session by ID */
+    getSession: (id: string) => ExplainabilitySession | undefined;
+    /** Remove a session */
+    removeSession: (id: string) => void;
+    /** Clear all sessions */
+    clearSessions: () => void;
+}
+export declare const useExplainabilityStore: import("zustand").UseBoundStore<import("zustand").StoreApi<ExplainabilityStoreState>>;
+//# sourceMappingURL=explainability-store.d.ts.map

package/dist/state/explainability-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainability-store.d.ts","sourceRoot":"","sources":["../../src/state/explainability-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErE,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAEhD,8BAA8B;IAC9B,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAEjE,6DAA6D;IAC7D,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,qBAAqB,CAAC,KAAK,IAAI,CAAC;IAE7E,0BAA0B;IAC1B,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,qBAAqB,GAAG,SAAS,CAAC;IAE9D,uBAAuB;IACvB,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpC,yBAAyB;IACzB,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,eAAO,MAAM,sBAAsB,uFAiClC,CAAC"}

package/dist/state/explainability.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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
+ */
+import type { ExplainEvent } from "@trustgraph/client";
+import { type ExplainabilitySession } from "../utils/explainability";
+export interface UseExplainabilityOptions {
+    flow?: string;
+    collection?: string;
+    /** Trace provenance for selected edges (default: true) */
+    traceProvenance?: boolean;
+}
+export interface UseExplainabilityResult {
+    /** Add an explain event (wire this to graphRag callbacks.onExplain) */
+    addEvent: (event: ExplainEvent) => void;
+    /** Current session data (React state - may lag behind ref) */
+    session: ExplainabilitySession;
+    /** Ref-backed session that's always immediately up-to-date (no render delay) */
+    sessionRef: React.RefObject<ExplainabilitySession>;
+    /** Raw events received */
+    events: ExplainEvent[];
+    /** Whether unpacking is in progress (React state) */
+    isUnpacking: boolean;
+    /** Ref-backed processing flag - always immediately up-to-date */
+    isProcessingRef: React.RefObject<boolean>;
+    /** Any error during unpacking */
+    error: string | null;
+    /** Reset the session */
+    reset: () => void;
+}
+/**
+ * Hook for managing explainability during inference
+ */
+export declare const useExplainability: (options?: UseExplainabilityOptions) => UseExplainabilityResult;
+export type { ExplainabilitySession, QuestionEvent, ExplorationEvent, FocusEvent, SynthesisEvent, SelectedEdge, ProvenanceChain, ProvenanceChainItem, } from "../utils/explainability";
+//# sourceMappingURL=explainability.d.ts.map

package/dist/state/explainability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainability.d.ts","sourceRoot":"","sources":["../../src/state/explainability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAU,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAKL,KAAK,qBAAqB,EAM3B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACxC,8DAA8D;IAC9D,OAAO,EAAE,qBAAqB,CAAC;IAC/B,gFAAgF;IAChF,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC;IACnD,0BAA0B;IAC1B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,qDAAqD;IACrD,WAAW,EAAE,OAAO,CAAC;IACrB,iEAAiE;IACjE,eAAe,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC1C,iCAAiC;IACjC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,wBAAwB;IACxB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAS,wBAA6B,KACrC,uBA2TF,CAAC;AAGF,YAAY,EACV,qBAAqB,EACrB,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,YAAY,EACZ,eAAe,EACf,mBAAmB,GACpB,MAAM,yBAAyB,CAAC"}

package/dist/state/inference.d.ts

@@ -1,4 +1,4 @@
-import type { EntityMatch } from "@trustgraph/client";
+import type { EntityMatch, ExplainEvent } from "@trustgraph/client";
 export interface GraphRagOptions {
     entityLimit?: number;
     tripleLimit?: number;
@@ -8,9 +8,11 @@ export interface GraphRagOptions {
 export interface GraphRagResult {
     response: string;
     entities: EntityMatch[];
+    explainEvents?: ExplainEvent[];
 }
 export interface GraphRagCallbacks {
     onChunk?: (chunk: string, complete: boolean) => void;
+    onExplain?: (event: ExplainEvent) => void;
     onError?: (error: string) => void;
 }
 export interface TextCompletionCallbacks {

package/dist/state/inference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inference.d.ts","sourceRoot":"","sources":["../../src/state/inference.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IACrD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IACrD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACxD,SAAS,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9D,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACxD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,WAAU;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO;;eAiBhD,MAAM;kBACH,eAAe;oBACb,MAAM;oBACN,iBAAiB;;;sBAoDf,MAAM;eACb,MAAM;oBACD,uBAAuB;;;eAoC5B,MAAM;oBACD,cAAc;;;CA0C/B,CAAC"}
+{"version":3,"file":"inference.d.ts","sourceRoot":"","sources":["../../src/state/inference.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEpE,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IACrD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAC1C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IACrD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACxD,SAAS,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9D,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACxD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,WAAU;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO;;eAkBhD,MAAM;kBACH,eAAe;oBACb,MAAM;oBACN,iBAAiB;;;sBAgEf,MAAM;eACb,MAAM;oBACD,uBAAuB;;;eAoC5B,MAAM;oBACD,cAAc;;;CA0C/B,CAAC"}

package/dist/state/provenance.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Hook for tracing provenance chains in the knowledge graph
+ * Follows prov:wasDerivedFrom relationships from any entity to its source documents
+ */
+import type { ProvenanceChain } from "../utils/explainability";
+export interface UseProvenanceOptions {
+    flow?: string;
+    collection?: string;
+    /** Maximum depth to trace (default: 10) */
+    maxDepth?: number;
+}
+export interface UseProvenanceResult {
+    /** Trace provenance chain from a URI to root */
+    traceChain: (uri: string) => Promise<ProvenanceChain>;
+    /** Trace provenance for an edge (s, p, o) - finds reifying statements first */
+    traceEdgeProvenance: (s: string, p: string, o: string) => Promise<ProvenanceChain[]>;
+    /** Resolve label for a URI (uses cache) */
+    resolveLabel: (uri: string) => Promise<string>;
+    /** Clear the label cache */
+    clearCache: () => void;
+    /** Whether any trace operation is in progress */
+    isTracing: boolean;
+}
+/**
+ * Hook for tracing provenance chains
+ */
+export declare const useProvenance: (options?: UseProvenanceOptions) => UseProvenanceResult;
+//# sourceMappingURL=provenance.d.ts.map

package/dist/state/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/state/provenance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,yBAAyB,CAAC;AAGpF,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACtD,+EAA+E;IAC/E,mBAAmB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACrF,2CAA2C;IAC3C,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,4BAA4B;IAC5B,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,UAAS,oBAAyB,KAAG,mBAuNlE,CAAC"}

package/dist/utils/explainability.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Explainability utilities for parsing and structuring explain events
+ */
+import type { Triple, Term } from "@trustgraph/client";
+export type ExplainEventType = "question" | "exploration" | "focus" | "synthesis" | "unknown";
+export interface QuestionEvent {
+    type: "question";
+    explainId: string;
+    explainGraph: string;
+    query?: string;
+    timestamp?: string;
+}
+export interface ExplorationEvent {
+    type: "exploration";
+    explainId: string;
+    explainGraph: string;
+    edgeCount?: number;
+}
+export interface SelectedEdge {
+    /** The actual edge as (s, p, o) URIs */
+    edge: {
+        s: string;
+        p: string;
+        o: string;
+    };
+    /** Human-readable labels for the edge */
+    labels?: {
+        s: string;
+        p: string;
+        o: string;
+    };
+    /** LLM's reasoning for selecting this edge */
+    reasoning?: string;
+    /** Provenance chain to source documents */
+    sources?: ProvenanceChainItem[];
+}
+export interface FocusEvent {
+    type: "focus";
+    explainId: string;
+    explainGraph: string;
+    /** URIs of edge selection entities */
+    edgeSelectionUris: string[];
+    /** Fully resolved selected edges (populated after unpacking) */
+    selectedEdges?: SelectedEdge[];
+}
+export interface SynthesisEvent {
+    type: "synthesis";
+    explainId: string;
+    explainGraph: string;
+    /** Content length (full content is streamed separately) */
+    contentLength?: number;
+}
+export type StructuredExplainEvent = QuestionEvent | ExplorationEvent | FocusEvent | SynthesisEvent;
+export interface ProvenanceChainItem {
+    uri: string;
+    label: string;
+}
+export interface ProvenanceChain {
+    /** The chain from leaf to root (e.g., chunk → page → document) */
+    chain: ProvenanceChainItem[];
+    /** The root document URI */
+    documentUri?: string;
+    /** The root document label/title */
+    documentLabel?: string;
+}
+export interface ExplainabilitySession {
+    question?: QuestionEvent;
+    exploration?: ExplorationEvent;
+    focus?: FocusEvent;
+    synthesis?: SynthesisEvent;
+}
+/**
+ * Extract event type from explainId URI
+ * e.g., "urn:trustgraph:question:abc123" → "question"
+ */
+export declare function getEventType(explainId: string): ExplainEventType;
+/**
+ * Get term value from a Term object
+ */
+export declare function getTermValue(term: Term): string;
+/**
+ * Extract quoted triple from a Term
+ */
+export declare function extractQuotedTriple(term: Term): {
+    s: string;
+    p: string;
+    o: string;
+} | null;
+/**
+ * Parse triples for a question event
+ */
+export declare function parseQuestionTriples(explainId: string, explainGraph: string, triples: Triple[]): QuestionEvent;
+/**
+ * Parse triples for an exploration event
+ */
+export declare function parseExplorationTriples(explainId: string, explainGraph: string, triples: Triple[]): ExplorationEvent;
+/**
+ * Parse triples for a focus event
+ */
+export declare function parseFocusTriples(explainId: string, explainGraph: string, triples: Triple[]): FocusEvent;
+/**
+ * Parse triples for a synthesis event
+ */
+export declare function parseSynthesisTriples(explainId: string, explainGraph: string, triples: Triple[]): SynthesisEvent;
+/**
+ * Parse triples for an edge selection entity
+ */
+export declare function parseEdgeSelectionTriples(triples: Triple[]): {
+    edge: {
+        s: string;
+        p: string;
+        o: string;
+    } | null;
+    reasoning: string | null;
+};
+/**
+ * Parse triples based on event type
+ */
+export declare function parseExplainTriples(explainId: string, explainGraph: string, triples: Triple[]): StructuredExplainEvent | null;
+//# sourceMappingURL=explainability.d.ts.map

package/dist/utils/explainability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainability.d.ts","sourceRoot":"","sources":["../../src/utils/explainability.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trustgraph/react-state",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "description": "React state management hooks for TrustGraph applications",
   "type": "module",
   "main": "dist/index.cjs",