Updated explainability taxonomy:

GraphRAG: tg:Question → tg:Exploration → tg:Focus → tg:Synthesis

Agent: tg:Question → tg:Analysis(s) → tg:Conclusion

All entities also have their PROV-O type (prov:Activity or prov:Entity).

Updated commit message:

Add provenance recording to React agent loop

Enables agent sessions to be traced and debugged using the same
explainability infrastructure as GraphRAG.

Entity types follow human reasoning patterns:
- tg:Question - the user's query (shared with GraphRAG)
- tg:Analysis - each think/act/observe cycle
- tg:Conclusion - the final answer

Also adds explicit TG types to GraphRAG entities:
- tg:Question, tg:Exploration, tg:Focus, tg:Synthesis

All types retain their PROV-O base types (prov:Activity, prov:Entity).

Changes:
- Add session_id and collection fields to AgentRequest schema
- Add explainability entity types to namespaces.py
- Create agent provenance triple generators
- Register explainability producer in agent service
- Emit provenance triples during agent execution
- Update CLI tools to detect and render both trace types

trustgraph-base/trustgraph/provenance/__init__.py

@@ -69,9 +69,11 @@ from . namespaces import (
     TG_SOURCE_TEXT, TG_SOURCE_CHAR_OFFSET, TG_SOURCE_CHAR_LENGTH,
     # Query-time provenance predicates
     TG_QUERY, TG_EDGE_COUNT, TG_SELECTED_EDGE, TG_REASONING, TG_CONTENT,
+    # Explainability entity types
+    TG_QUESTION, TG_EXPLORATION, TG_FOCUS, TG_SYNTHESIS,
+    TG_ANALYSIS, TG_CONCLUSION,
     # Agent provenance predicates
     TG_THOUGHT, TG_ACTION, TG_ARGUMENTS, TG_OBSERVATION, TG_ANSWER,
-    TG_AGENT_SESSION, TG_AGENT_ITERATION, TG_AGENT_FINAL,
     # Named graphs
     GRAPH_DEFAULT, GRAPH_SOURCE, GRAPH_RETRIEVAL,
 )
@@ -138,9 +140,11 @@ __all__ = [
     "TG_SOURCE_TEXT", "TG_SOURCE_CHAR_OFFSET", "TG_SOURCE_CHAR_LENGTH",
     # Query-time provenance predicates
     "TG_QUERY", "TG_EDGE_COUNT", "TG_SELECTED_EDGE", "TG_REASONING", "TG_CONTENT",
+    # Explainability entity types
+    "TG_QUESTION", "TG_EXPLORATION", "TG_FOCUS", "TG_SYNTHESIS",
+    "TG_ANALYSIS", "TG_CONCLUSION",
     # Agent provenance predicates
     "TG_THOUGHT", "TG_ACTION", "TG_ARGUMENTS", "TG_OBSERVATION", "TG_ANSWER",
-    "TG_AGENT_SESSION", "TG_AGENT_ITERATION", "TG_AGENT_FINAL",
     # Named graphs
     "GRAPH_DEFAULT", "GRAPH_SOURCE", "GRAPH_RETRIEVAL",
     # Triple builders

trustgraph-base/trustgraph/provenance/agent.py

@@ -2,9 +2,9 @@
 Helper functions to build PROV-O triples for agent provenance.
 
 Agent provenance tracks the reasoning trace of ReAct agent sessions:
-- AgentSession: The root entity with query and timestamp
-- AgentIteration: Each think/act/observe cycle
-- AgentFinal: The final answer
+- Question: The root activity with query and timestamp
+- Analysis: Each think/act/observe cycle
+- Conclusion: The final answer
 """
 
 import json
@@ -15,9 +15,9 @@ from .. schema import Triple, Term, IRI, LITERAL
 
 from . namespaces import (
     RDF_TYPE, RDFS_LABEL,
-    PROV_ENTITY, PROV_WAS_DERIVED_FROM, PROV_STARTED_AT_TIME,
+    PROV_ACTIVITY, PROV_ENTITY, PROV_WAS_DERIVED_FROM, PROV_STARTED_AT_TIME,
     TG_QUERY, TG_THOUGHT, TG_ACTION, TG_ARGUMENTS, TG_OBSERVATION, TG_ANSWER,
-    TG_AGENT_SESSION, TG_AGENT_ITERATION, TG_AGENT_FINAL,
+    TG_QUESTION, TG_ANALYSIS, TG_CONCLUSION,
 )
 
 
@@ -42,10 +42,10 @@ def agent_session_triples(
     timestamp: Optional[str] = None,
 ) -> List[Triple]:
     """
-    Build triples for an agent session start.
+    Build triples for an agent session start (Question).
 
     Creates:
-    - Entity declaration for the session
+    - Activity declaration with tg:Question type
     - Query text and timestamp
 
     Args:
@@ -60,8 +60,9 @@ def agent_session_triples(
         timestamp = datetime.utcnow().isoformat() + "Z"
 
     return [
-        _triple(session_uri, RDF_TYPE, _iri(TG_AGENT_SESSION)),
-        _triple(session_uri, RDFS_LABEL, _literal("Agent Session")),
+        _triple(session_uri, RDF_TYPE, _iri(PROV_ACTIVITY)),
+        _triple(session_uri, RDF_TYPE, _iri(TG_QUESTION)),
+        _triple(session_uri, RDFS_LABEL, _literal("Agent Question")),
         _triple(session_uri, PROV_STARTED_AT_TIME, _literal(timestamp)),
         _triple(session_uri, TG_QUERY, _literal(query)),
     ]
@@ -76,10 +77,10 @@ def agent_iteration_triples(
     observation: str,
 ) -> List[Triple]:
     """
-    Build triples for one agent iteration (think/act/observe cycle).
+    Build triples for one agent iteration (Analysis - think/act/observe cycle).
 
     Creates:
-    - Entity declaration for the iteration
+    - Entity declaration with tg:Analysis type
     - wasDerivedFrom link to parent (previous iteration or session)
     - Thought, action, arguments, and observation data
 
@@ -95,8 +96,9 @@ def agent_iteration_triples(
         List of Triple objects
     """
     triples = [
-        _triple(iteration_uri, RDF_TYPE, _iri(TG_AGENT_ITERATION)),
-        _triple(iteration_uri, RDFS_LABEL, _literal(f"Iteration: {action}")),
+        _triple(iteration_uri, RDF_TYPE, _iri(PROV_ENTITY)),
+        _triple(iteration_uri, RDF_TYPE, _iri(TG_ANALYSIS)),
+        _triple(iteration_uri, RDFS_LABEL, _literal(f"Analysis: {action}")),
         _triple(iteration_uri, PROV_WAS_DERIVED_FROM, _iri(parent_uri)),
         _triple(iteration_uri, TG_THOUGHT, _literal(thought)),
         _triple(iteration_uri, TG_ACTION, _literal(action)),
@@ -113,10 +115,10 @@ def agent_final_triples(
     answer: str,
 ) -> List[Triple]:
     """
-    Build triples for an agent final answer.
+    Build triples for an agent final answer (Conclusion).
 
     Creates:
-    - Entity declaration for the final answer
+    - Entity declaration with tg:Conclusion type
     - wasDerivedFrom link to parent (last iteration or session)
     - The answer text
 
@@ -129,8 +131,9 @@ def agent_final_triples(
         List of Triple objects
     """
     return [
-        _triple(final_uri, RDF_TYPE, _iri(TG_AGENT_FINAL)),
-        _triple(final_uri, RDFS_LABEL, _literal("Final Answer")),
+        _triple(final_uri, RDF_TYPE, _iri(PROV_ENTITY)),
+        _triple(final_uri, RDF_TYPE, _iri(TG_CONCLUSION)),
+        _triple(final_uri, RDFS_LABEL, _literal("Conclusion")),
         _triple(final_uri, PROV_WAS_DERIVED_FROM, _iri(parent_uri)),
         _triple(final_uri, TG_ANSWER, _literal(answer)),
     ]

trustgraph-base/trustgraph/provenance/namespaces.py

@@ -68,15 +68,20 @@ TG_REASONING = TG + "reasoning"
 TG_CONTENT = TG + "content"
 TG_DOCUMENT = TG + "document"  # Reference to document in librarian
 
+# Explainability entity types (used by both GraphRAG and Agent)
+TG_QUESTION = TG + "Question"
+TG_EXPLORATION = TG + "Exploration"
+TG_FOCUS = TG + "Focus"
+TG_SYNTHESIS = TG + "Synthesis"
+TG_ANALYSIS = TG + "Analysis"
+TG_CONCLUSION = TG + "Conclusion"
+
 # Agent provenance predicates
 TG_THOUGHT = TG + "thought"
 TG_ACTION = TG + "action"
 TG_ARGUMENTS = TG + "arguments"
 TG_OBSERVATION = TG + "observation"
 TG_ANSWER = TG + "answer"
-TG_AGENT_SESSION = TG + "AgentSession"
-TG_AGENT_ITERATION = TG + "AgentIteration"
-TG_AGENT_FINAL = TG + "AgentFinal"
 
 # Named graph URIs for RDF datasets
 # These separate different types of data while keeping them in the same collection

trustgraph-base/trustgraph/provenance/triples.py

@@ -20,6 +20,8 @@ from . namespaces import (
     # Query-time provenance predicates
     TG_QUERY, TG_EDGE_COUNT, TG_SELECTED_EDGE, TG_EDGE, TG_REASONING, TG_CONTENT,
     TG_DOCUMENT,
+    # Explainability entity types
+    TG_QUESTION, TG_EXPLORATION, TG_FOCUS, TG_SYNTHESIS,
 )
 
 from . uris import activity_uri, agent_uri, edge_selection_uri
@@ -310,7 +312,8 @@ def question_triples(
 
     return [
         _triple(question_uri, RDF_TYPE, _iri(PROV_ACTIVITY)),
-        _triple(question_uri, RDFS_LABEL, _literal("GraphRAG question")),
+        _triple(question_uri, RDF_TYPE, _iri(TG_QUESTION)),
+        _triple(question_uri, RDFS_LABEL, _literal("GraphRAG Question")),
         _triple(question_uri, PROV_STARTED_AT_TIME, _literal(timestamp)),
         _triple(question_uri, TG_QUERY, _literal(query)),
     ]
@@ -339,6 +342,7 @@ def exploration_triples(
     """
     return [
         _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_EDGE_COUNT, _literal(edge_count)),
@@ -383,6 +387,7 @@ def focus_triples(
     """
     triples = [
         _triple(focus_uri, RDF_TYPE, _iri(PROV_ENTITY)),
+        _triple(focus_uri, RDF_TYPE, _iri(TG_FOCUS)),
         _triple(focus_uri, RDFS_LABEL, _literal("Focus")),
         _triple(focus_uri, PROV_WAS_DERIVED_FROM, _iri(exploration_uri)),
     ]
@@ -443,6 +448,7 @@ def synthesis_triples(
     """
     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(focus_uri)),
     ]