GraphRAG Query-Time Explainability (#677)

Implements full explainability pipeline for GraphRAG queries, enabling
traceability from answers back to source documents.

Renamed throughout for clarity:
- provenance_callback → explain_callback
- provenance_id → explain_id
- provenance_collection → explain_collection
- message_type "provenance" → "explain"
- Queue name "provenance" → "explainability"

GraphRAG queries now emit explainability events as they execute:
1. Session - query text and timestamp
2. Retrieval - edges retrieved from subgraph
3. Selection - selected edges with LLM reasoning (JSONL with id +
   reasoning)
4. Answer - reference to synthesized response

Events stream via explain_callback during query(), enabling
real-time UX.

- Answers stored in librarian service (not inline in graph - too large)
- Document ID as URN: urn:trustgraph:answer:{session_id}
- Graph stores tg:document reference (IRI) to librarian document
- Added librarian producer/consumer to graph-rag service

- get_labelgraph() now returns (labeled_edges, uri_map)
- uri_map maps edge_id(label_s, label_p, label_o) →
  (uri_s, uri_p, uri_o)
- Explainability data stores original URIs, not labels
- Enables tracing edges back to reifying statements via tg:reifies

- Added serialize_triple() to query service (matches storage format)
- get_term_value() now handles TRIPLE type terms
- Enables querying by quoted triple in object position:
  ?stmt tg:reifies <<s p o>>

- Displays real-time explainability events during query
- Resolves rdfs:label for edge components (s, p, o)
- Traces source chain via prov:wasDerivedFrom to root document
- Output: "Source: Chunk 1 → Page 2 → Document Title"
- Label caching to avoid repeated queries

GraphRagResponse:
- explain_id: str | None
- explain_collection: str | None
- message_type: str ("chunk" or "explain")
- end_of_session: bool

trustgraph-base/trustgraph/provenance/:
- namespaces.py - Added TG_DOCUMENT predicate
- triples.py - answer_triples() supports document_id reference
- uris.py - Added edge_selection_uri()

trustgraph-base/trustgraph/schema/services/retrieval.py:
- GraphRagResponse with explain_id, explain_collection, end_of_session

trustgraph-flow/trustgraph/retrieval/graph_rag/:
- graph_rag.py - URI preservation, streaming answer accumulation
- rag.py - Librarian integration, real-time explain emission

trustgraph-flow/trustgraph/query/triples/cassandra/service.py:
- Quoted triple serialization for query matching

trustgraph-cli/trustgraph/cli/invoke_graph_rag.py:
- Full explainability display with label resolution and source tracing

trustgraph-base/trustgraph/api/async_socket_client.py

@@ -110,15 +110,25 @@ class AsyncSocketClient:
 
                     # Parse different chunk types
                     chunk = self._parse_chunk(resp)
-                    yield chunk
+                    if chunk is not None:  # Skip provenance messages in streaming
+                        yield chunk
 
-                    # Check if this is the final chunk
-                    if resp.get("end_of_stream") or resp.get("end_of_dialog") or response.get("complete"):
+                    # Check if this is the final message
+                    # end_of_session indicates entire session is complete (including provenance)
+                    # end_of_dialog is for agent dialogs
+                    # complete is from the gateway envelope
+                    if resp.get("end_of_session") or resp.get("end_of_dialog") or response.get("complete"):
                         break
 
     def _parse_chunk(self, resp: Dict[str, Any]):
-        """Parse response chunk into appropriate type"""
+        """Parse response chunk into appropriate type. Returns None for non-content messages."""
         chunk_type = resp.get("chunk_type")
+        message_type = resp.get("message_type")
+
+        # Handle new GraphRAG message format with message_type
+        if message_type == "provenance":
+            # Provenance messages are not yielded to user - they're metadata
+            return None
 
         if chunk_type == "thought":
             return AgentThought(
@@ -143,7 +153,7 @@ class AsyncSocketClient:
                 end_of_message=resp.get("end_of_message", False)
             )
         else:
-            # RAG-style chunk (or generic chunk)
+            # RAG-style chunk (or generic chunk with message_type="chunk")
             # Text-completion uses "response" field, RAG uses "chunk" field, Prompt uses "text" field
             content = resp.get("response", resp.get("chunk", resp.get("text", "")))
             return RAGChunk(

trustgraph-base/trustgraph/api/socket_client.py

@@ -11,7 +11,7 @@ import websockets
 from typing import Optional, Dict, Any, Iterator, Union, List
 from threading import Lock
 
-from . types import AgentThought, AgentObservation, AgentAnswer, RAGChunk, StreamingChunk
+from . types import AgentThought, AgentObservation, AgentAnswer, RAGChunk, StreamingChunk, ProvenanceEvent
 from . exceptions import ProtocolException, raise_from_error_dict
 
 
@@ -310,15 +310,28 @@ class SocketClient:
 
                     # Parse different chunk types
                     chunk = self._parse_chunk(resp)
-                    yield chunk
+                    if chunk is not None:  # Skip provenance messages in streaming
+                        yield chunk
 
-                    # Check if this is the final chunk
-                    if resp.get("end_of_stream") or resp.get("end_of_dialog") or response.get("complete"):
+                    # Check if this is the final message
+                    # end_of_session indicates entire session is complete (including provenance)
+                    # end_of_dialog is for agent dialogs
+                    # complete is from the gateway envelope
+                    if resp.get("end_of_session") or resp.get("end_of_dialog") or response.get("complete"):
                         break
 
-    def _parse_chunk(self, resp: Dict[str, Any]) -> StreamingChunk:
-        """Parse response chunk into appropriate type"""
+    def _parse_chunk(self, resp: Dict[str, Any], include_provenance: bool = False) -> Optional[StreamingChunk]:
+        """Parse response chunk into appropriate type. Returns None for non-content messages."""
         chunk_type = resp.get("chunk_type")
+        message_type = resp.get("message_type")
+
+        # Handle new GraphRAG message format with message_type
+        if message_type == "provenance":
+            if include_provenance:
+                # Return provenance event for explainability
+                return ProvenanceEvent(provenance_id=resp.get("provenance_id", ""))
+            # Provenance messages are not yielded to user - they're metadata
+            return None
 
         if chunk_type == "thought":
             return AgentThought(
@@ -360,7 +373,7 @@ class SocketClient:
                 end_of_dialog=resp.get("end_of_dialog", False)
             )
         else:
-            # RAG-style chunk (or generic chunk)
+            # RAG-style chunk (or generic chunk with message_type="chunk")
             # Text-completion uses "response" field, RAG uses "chunk" field, Prompt uses "text" field
             content = resp.get("response", resp.get("chunk", resp.get("text", "")))
             return RAGChunk(

trustgraph-base/trustgraph/api/types.py

@@ -202,3 +202,29 @@ class RAGChunk(StreamingChunk):
     chunk_type: str = "rag"
     end_of_stream: bool = False
     error: Optional[Dict[str, str]] = None
+
+@dataclasses.dataclass
+class ProvenanceEvent:
+    """
+    Provenance event for explainability.
+
+    Emitted during GraphRAG queries when explainable mode is enabled.
+    Each event represents a provenance node created during query processing.
+
+    Attributes:
+        provenance_id: URI of the provenance node (e.g., urn:trustgraph:session:abc123)
+        event_type: Type of provenance event (session, retrieval, selection, answer)
+    """
+    provenance_id: str
+    event_type: str = ""  # Derived from provenance_id (session, retrieval, selection, answer)
+
+    def __post_init__(self):
+        # Extract event type from provenance_id
+        if "session" in self.provenance_id:
+            self.event_type = "session"
+        elif "retrieval" in self.provenance_id:
+            self.event_type = "retrieval"
+        elif "selection" in self.provenance_id:
+            self.event_type = "selection"
+        elif "answer" in self.provenance_id:
+            self.event_type = "answer"