Document RAG explainability is now complete. Here's a summary of the

changes made:

Schema Changes:
- trustgraph-base/trustgraph/schema/services/retrieval.py: Added
  explain_id and explain_graph fields to DocumentRagResponse
- trustgraph-base/trustgraph/messaging/translators/retrieval.py:
  Updated translator to handle explainability fields

Provenance Changes:
- trustgraph-base/trustgraph/provenance/namespaces.py: Added
  TG_CHUNK_COUNT and TG_SELECTED_CHUNK predicates
- trustgraph-base/trustgraph/provenance/uris.py: Added
  docrag_question_uri, docrag_exploration_uri, docrag_synthesis_uri
  generators
- trustgraph-base/trustgraph/provenance/triples.py: Added
  docrag_question_triples, docrag_exploration_triples,
  docrag_synthesis_triples builders
- trustgraph-base/trustgraph/provenance/__init__.py: Exported all
  new Document RAG functions and predicates

Service Changes:
- trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py:
  Added explainability callback support and triple emission at each
  phase (Question → Exploration → Synthesis)
- trustgraph-flow/trustgraph/retrieval/document_rag/rag.py:
  Registered explainability producer and wired up the callback

Documentation:
- docs/tech-specs/agent-explainability.md: Added Document RAG entity
  types and provenance model documentation

Document RAG Provenance Model:
Question (urn:trustgraph:docrag:{uuid})
    │
    │  tg:query, prov:startedAtTime
    │  rdf:type = prov:Activity, tg:Question
    │
    ↓ prov:wasGeneratedBy
    │
Exploration (urn:trustgraph:docrag:{uuid}/exploration)
    │
    │  tg:chunkCount, tg:selectedChunk (multiple)
    │  rdf:type = prov:Entity, tg:Exploration
    │
    ↓ prov:wasDerivedFrom
    │
Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
    │
    │  tg:content = "The answer..."
    │  rdf:type = prov:Entity, tg:Synthesis

trustgraph-base/trustgraph/messaging/translators/retrieval.py

@@ -38,6 +38,16 @@ class DocumentRagResponseTranslator(MessageTranslator):
         if obj.response is not None:
             result["response"] = obj.response
 
+        # Include explain_id for explain messages
+        explain_id = getattr(obj, "explain_id", None)
+        if explain_id:
+            result["explain_id"] = explain_id
+
+        # Include explain_graph for explain messages (named graph filter)
+        explain_graph = getattr(obj, "explain_graph", None)
+        if explain_graph is not None:
+            result["explain_graph"] = explain_graph
+
         # Include end_of_stream flag
         result["end_of_stream"] = getattr(obj, "end_of_stream", False)
 

trustgraph-base/trustgraph/provenance/__init__.py

@@ -40,7 +40,7 @@ from . uris import (
     activity_uri,
     statement_uri,
     agent_uri,
-    # Query-time provenance URIs
+    # Query-time provenance URIs (GraphRAG)
     question_uri,
     exploration_uri,
     focus_uri,
@@ -49,6 +49,10 @@ from . uris import (
     agent_session_uri,
     agent_iteration_uri,
     agent_final_uri,
+    # Document RAG provenance URIs
+    docrag_question_uri,
+    docrag_exploration_uri,
+    docrag_synthesis_uri,
 )
 
 # Namespace constants
@@ -67,8 +71,10 @@ from . namespaces import (
     TG_CHUNK_SIZE, TG_CHUNK_OVERLAP, TG_COMPONENT_VERSION,
     TG_LLM_MODEL, TG_ONTOLOGY, TG_EMBEDDING_MODEL,
     TG_SOURCE_TEXT, TG_SOURCE_CHAR_OFFSET, TG_SOURCE_CHAR_LENGTH,
-    # Query-time provenance predicates
+    # Query-time provenance predicates (GraphRAG)
     TG_QUERY, TG_EDGE_COUNT, TG_SELECTED_EDGE, TG_REASONING, TG_CONTENT,
+    # Query-time provenance predicates (DocumentRAG)
+    TG_CHUNK_COUNT, TG_SELECTED_CHUNK,
     # Explainability entity types
     TG_QUESTION, TG_EXPLORATION, TG_FOCUS, TG_SYNTHESIS,
     TG_ANALYSIS, TG_CONCLUSION,
@@ -83,11 +89,15 @@ from . triples import (
     document_triples,
     derived_entity_triples,
     triple_provenance_triples,
-    # Query-time provenance triple builders
+    # Query-time provenance triple builders (GraphRAG)
     question_triples,
     exploration_triples,
     focus_triples,
     synthesis_triples,
+    # Query-time provenance triple builders (DocumentRAG)
+    docrag_question_triples,
+    docrag_exploration_triples,
+    docrag_synthesis_triples,
     # Utility
     set_graph,
 )
@@ -127,6 +137,10 @@ __all__ = [
     "agent_session_uri",
     "agent_iteration_uri",
     "agent_final_uri",
+    # Document RAG provenance URIs
+    "docrag_question_uri",
+    "docrag_exploration_uri",
+    "docrag_synthesis_uri",
     # Namespaces
     "PROV", "PROV_ENTITY", "PROV_ACTIVITY", "PROV_AGENT",
     "PROV_WAS_DERIVED_FROM", "PROV_WAS_GENERATED_BY",
@@ -138,8 +152,10 @@ __all__ = [
     "TG_CHUNK_SIZE", "TG_CHUNK_OVERLAP", "TG_COMPONENT_VERSION",
     "TG_LLM_MODEL", "TG_ONTOLOGY", "TG_EMBEDDING_MODEL",
     "TG_SOURCE_TEXT", "TG_SOURCE_CHAR_OFFSET", "TG_SOURCE_CHAR_LENGTH",
-    # Query-time provenance predicates
+    # Query-time provenance predicates (GraphRAG)
     "TG_QUERY", "TG_EDGE_COUNT", "TG_SELECTED_EDGE", "TG_REASONING", "TG_CONTENT",
+    # Query-time provenance predicates (DocumentRAG)
+    "TG_CHUNK_COUNT", "TG_SELECTED_CHUNK",
     # Explainability entity types
     "TG_QUESTION", "TG_EXPLORATION", "TG_FOCUS", "TG_SYNTHESIS",
     "TG_ANALYSIS", "TG_CONCLUSION",
@@ -151,11 +167,15 @@ __all__ = [
     "document_triples",
     "derived_entity_triples",
     "triple_provenance_triples",
-    # Query-time provenance triple builders
+    # Query-time provenance triple builders (GraphRAG)
     "question_triples",
     "exploration_triples",
     "focus_triples",
     "synthesis_triples",
+    # Query-time provenance triple builders (DocumentRAG)
+    "docrag_question_triples",
+    "docrag_exploration_triples",
+    "docrag_synthesis_triples",
     # Agent provenance triple builders
     "agent_session_triples",
     "agent_iteration_triples",

trustgraph-base/trustgraph/provenance/namespaces.py

@@ -59,7 +59,7 @@ TG_SOURCE_TEXT = TG + "sourceText"
 TG_SOURCE_CHAR_OFFSET = TG + "sourceCharOffset"
 TG_SOURCE_CHAR_LENGTH = TG + "sourceCharLength"
 
-# Query-time provenance predicates
+# Query-time provenance predicates (GraphRAG)
 TG_QUERY = TG + "query"
 TG_EDGE_COUNT = TG + "edgeCount"
 TG_SELECTED_EDGE = TG + "selectedEdge"
@@ -68,6 +68,10 @@ TG_REASONING = TG + "reasoning"
 TG_CONTENT = TG + "content"
 TG_DOCUMENT = TG + "document"  # Reference to document in librarian
 
+# Query-time provenance predicates (DocumentRAG)
+TG_CHUNK_COUNT = TG + "chunkCount"
+TG_SELECTED_CHUNK = TG + "selectedChunk"
+
 # Explainability entity types (used by both GraphRAG and Agent)
 TG_QUESTION = TG + "Question"
 TG_EXPLORATION = TG + "Exploration"

trustgraph-base/trustgraph/provenance/triples.py

@@ -17,9 +17,11 @@ from . namespaces import (
     TG_CHUNK_INDEX, TG_CHAR_OFFSET, TG_CHAR_LENGTH,
     TG_CHUNK_SIZE, TG_CHUNK_OVERLAP, TG_COMPONENT_VERSION,
     TG_LLM_MODEL, TG_ONTOLOGY, TG_REIFIES,
-    # Query-time provenance predicates
+    # Query-time provenance predicates (GraphRAG)
     TG_QUERY, TG_EDGE_COUNT, TG_SELECTED_EDGE, TG_EDGE, TG_REASONING, TG_CONTENT,
     TG_DOCUMENT,
+    # Query-time provenance predicates (DocumentRAG)
+    TG_CHUNK_COUNT, TG_SELECTED_CHUNK,
     # Explainability entity types
     TG_QUESTION, TG_EXPLORATION, TG_FOCUS, TG_SYNTHESIS,
 )
@@ -461,3 +463,119 @@ def synthesis_triples(
         triples.append(_triple(synthesis_uri, TG_CONTENT, _literal(answer_text)))
 
     return triples
+
+
+# Document RAG provenance triple builders
+#
+# Document RAG uses a subset of GraphRAG's model:
+#   Question    - What was asked
+#   Exploration - Chunks retrieved from document store
+#   Synthesis   - The final answer (no Focus step)
+
+def docrag_question_triples(
+    question_uri: str,
+    query: str,
+    timestamp: Optional[str] = None,
+) -> List[Triple]:
+    """
+    Build triples for a document RAG question activity.
+
+    Creates:
+    - Activity declaration with tg:Question type
+    - Query text and timestamp
+
+    Args:
+        question_uri: URI of the question (from docrag_question_uri)
+        query: The user's query text
+        timestamp: ISO timestamp (defaults to now)
+
+    Returns:
+        List of Triple objects
+    """
+    if timestamp is None:
+        timestamp = datetime.utcnow().isoformat() + "Z"
+
+    return [
+        _triple(question_uri, RDF_TYPE, _iri(PROV_ACTIVITY)),
+        _triple(question_uri, RDF_TYPE, _iri(TG_QUESTION)),
+        _triple(question_uri, RDFS_LABEL, _literal("DocumentRAG Question")),
+        _triple(question_uri, PROV_STARTED_AT_TIME, _literal(timestamp)),
+        _triple(question_uri, TG_QUERY, _literal(query)),
+    ]
+
+
+def docrag_exploration_triples(
+    exploration_uri: str,
+    question_uri: str,
+    chunk_count: int,
+    chunk_ids: Optional[List[str]] = None,
+) -> List[Triple]:
+    """
+    Build triples for a document RAG exploration entity (chunks retrieved).
+
+    Creates:
+    - Entity declaration with tg:Exploration type
+    - wasGeneratedBy link to question
+    - Chunk count and optional chunk references
+
+    Args:
+        exploration_uri: URI of the exploration entity
+        question_uri: URI of the parent question
+        chunk_count: Number of chunks retrieved
+        chunk_ids: Optional list of chunk URIs/IDs
+
+    Returns:
+        List of Triple objects
+    """
+    triples = [
+        _triple(exploration_uri, RDF_TYPE, _iri(PROV_ENTITY)),
+        _triple(exploration_uri, RDF_TYPE, _iri(TG_EXPLORATION)),
+        _triple(exploration_uri, RDFS_LABEL, _literal("Exploration")),
+        _triple(exploration_uri, PROV_WAS_GENERATED_BY, _iri(question_uri)),
+        _triple(exploration_uri, TG_CHUNK_COUNT, _literal(chunk_count)),
+    ]
+
+    # Add references to selected chunks
+    if chunk_ids:
+        for chunk_id in chunk_ids:
+            triples.append(_triple(exploration_uri, TG_SELECTED_CHUNK, _iri(chunk_id)))
+
+    return triples
+
+
+def docrag_synthesis_triples(
+    synthesis_uri: str,
+    exploration_uri: str,
+    answer_text: str = "",
+    document_id: Optional[str] = None,
+) -> List[Triple]:
+    """
+    Build triples for a document RAG synthesis entity (final answer).
+
+    Creates:
+    - Entity declaration with tg:Synthesis type
+    - wasDerivedFrom link to exploration (skips focus step)
+    - Either document reference or inline content
+
+    Args:
+        synthesis_uri: URI of the synthesis entity
+        exploration_uri: URI of the parent exploration entity
+        answer_text: The synthesized answer text (used if no document_id)
+        document_id: Optional librarian document ID (preferred over inline content)
+
+    Returns:
+        List of Triple objects
+    """
+    triples = [
+        _triple(synthesis_uri, RDF_TYPE, _iri(PROV_ENTITY)),
+        _triple(synthesis_uri, RDF_TYPE, _iri(TG_SYNTHESIS)),
+        _triple(synthesis_uri, RDFS_LABEL, _literal("Synthesis")),
+        _triple(synthesis_uri, PROV_WAS_DERIVED_FROM, _iri(exploration_uri)),
+    ]
+
+    if document_id:
+        triples.append(_triple(synthesis_uri, TG_DOCUMENT, _iri(document_id)))
+    elif answer_text:
+        triples.append(_triple(synthesis_uri, TG_CONTENT, _literal(answer_text)))
+
+    return triples

trustgraph-base/trustgraph/provenance/uris.py

@@ -184,3 +184,48 @@ def agent_final_uri(session_id: str) -> str:
         URN in format: urn:trustgraph:agent:{uuid}/final
     """
     return f"urn:trustgraph:agent:{session_id}/final"
+
+
+# Document RAG provenance URIs
+# These URIs use the urn:trustgraph:docrag: namespace to distinguish
+# document RAG provenance from graph RAG provenance
+
+def docrag_question_uri(session_id: str = None) -> str:
+    """
+    Generate URI for a document RAG question activity.
+
+    Args:
+        session_id: Optional UUID string. Auto-generates if not provided.
+
+    Returns:
+        URN in format: urn:trustgraph:docrag:{uuid}
+    """
+    if session_id is None:
+        session_id = str(uuid.uuid4())
+    return f"urn:trustgraph:docrag:{session_id}"
+
+
+def docrag_exploration_uri(session_id: str) -> str:
+    """
+    Generate URI for a document RAG exploration entity (chunks retrieved).
+
+    Args:
+        session_id: The session UUID.
+
+    Returns:
+        URN in format: urn:trustgraph:docrag:{uuid}/exploration
+    """
+    return f"urn:trustgraph:docrag:{session_id}/exploration"
+
+
+def docrag_synthesis_uri(session_id: str) -> str:
+    """
+    Generate URI for a document RAG synthesis entity (final answer).
+
+    Args:
+        session_id: The session UUID.
+
+    Returns:
+        URN in format: urn:trustgraph:docrag:{uuid}/synthesis
+    """
+    return f"urn:trustgraph:docrag:{session_id}/synthesis"

trustgraph-base/trustgraph/schema/services/retrieval.py

@@ -42,5 +42,7 @@ class DocumentRagQuery:
 @dataclass
 class DocumentRagResponse:
     error: Error | None = None
-    response: str = ""
+    response: str | None = ""
     end_of_stream: bool = False
+    explain_id: str | None = None     # Single explain URI (announced as created)
+    explain_graph: str | None = None  # Named graph where explain was stored (e.g., urn:graph:retrieval)