Adding explainability to the ReACT agent (#689)

* Added tech spec

* Add provenance recording to React agent loop

Enables agent sessions to be traced and debugged using the same
explainability infrastructure as GraphRAG. Agent traces record:
- Session start with query and timestamp
- Each iteration's thought, action, arguments, and observation
- Final answer with derivation chain

Changes:
- Add session_id and collection fields to AgentRequest schema
- Add agent predicates (TG_THOUGHT, TG_ACTION, etc.) to namespaces
- Create agent provenance triple generators in provenance/agent.py
- Register explainability producer in agent service
- Emit provenance triples during agent execution
- Update CLI tools to detect and render agent traces alongside GraphRAG

* 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

* 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

* Specific subtype that makes the retrieval mechanism immediately
obvious:

System: GraphRAG
TG Types on Question: tg:Question, tg:GraphRagQuestion
URI Pattern: urn:trustgraph:question:{uuid}
────────────────────────────────────────
System: Document RAG
TG Types on Question: tg:Question, tg:DocRagQuestion
URI Pattern: urn:trustgraph:docrag:{uuid}
────────────────────────────────────────
System: Agent
TG Types on Question: tg:Question, tg:AgentQuestion
URI Pattern: urn:trustgraph:agent:{uuid}
Files modified:
- trustgraph-base/trustgraph/provenance/namespaces.py - Added
TG_GRAPH_RAG_QUESTION, TG_DOC_RAG_QUESTION, TG_AGENT_QUESTION
- trustgraph-base/trustgraph/provenance/triples.py - Added subtype to
question_triples and docrag_question_triples
- trustgraph-base/trustgraph/provenance/agent.py - Added subtype to
agent_session_triples
- trustgraph-base/trustgraph/provenance/__init__.py - Exported new types
- docs/tech-specs/agent-explainability.md - Documented the subtypes

This allows:
- Query all questions: ?q rdf:type tg:Question
- Query only GraphRAG: ?q rdf:type tg:GraphRagQuestion
- Query only Document RAG: ?q rdf:type tg:DocRagQuestion
- Query only Agent: ?q rdf:type tg:AgentQuestion

* Fixed tests

trustgraph-cli/trustgraph/cli/list_explain_traces.py

@@ -1,8 +1,8 @@
 """
-List all GraphRAG sessions (questions) in a collection.
+List all explainability sessions (GraphRAG and Agent) in a collection.
 
 Queries for all questions stored in the retrieval graph and displays them
-with their session IDs and timestamps.
+with their session IDs, type (GraphRAG or Agent), and timestamps.
 
 Examples:
   tg-list-explain-traces -U trustgraph -C default
@@ -24,8 +24,14 @@ default_collection = 'default'
 # Predicates
 TG = "https://trustgraph.ai/ns/"
 TG_QUERY = TG + "query"
+TG_QUESTION = TG + "Question"
+TG_ANALYSIS = TG + "Analysis"
+TG_EXPLORATION = TG + "Exploration"
 PROV = "http://www.w3.org/ns/prov#"
 PROV_STARTED_AT_TIME = PROV + "startedAtTime"
+PROV_WAS_DERIVED_FROM = PROV + "wasDerivedFrom"
+PROV_WAS_GENERATED_BY = PROV + "wasGeneratedBy"
+RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
 
 # Retrieval graph
 RETRIEVAL_GRAPH = "urn:graph:retrieval"
@@ -117,8 +123,45 @@ def get_timestamp(socket, flow_id, user, collection, question_id):
     return ""
 
 
+def get_session_type(socket, flow_id, user, collection, session_id):
+    """
+    Get the type of session (Agent or GraphRAG).
+
+    Both have tg:Question type, so we distinguish by URI pattern
+    or by checking what's derived from it.
+    """
+    # Fast path: check URI pattern
+    if session_id.startswith("urn:trustgraph:agent:"):
+        return "Agent"
+    if session_id.startswith("urn:trustgraph:question:"):
+        return "GraphRAG"
+
+    # Check what's derived from this entity
+    derived = query_triples(
+        socket, flow_id, user, collection,
+        p=PROV_WAS_DERIVED_FROM, o=session_id, g=RETRIEVAL_GRAPH
+    )
+    generated = query_triples(
+        socket, flow_id, user, collection,
+        p=PROV_WAS_GENERATED_BY, o=session_id, g=RETRIEVAL_GRAPH
+    )
+
+    for s, p, o in derived + generated:
+        child_types = query_triples(
+            socket, flow_id, user, collection,
+            s=s, p=RDF_TYPE, g=RETRIEVAL_GRAPH
+        )
+        for _, _, child_type in child_types:
+            if child_type == TG_ANALYSIS:
+                return "Agent"
+            if child_type == TG_EXPLORATION:
+                return "GraphRAG"
+
+    return "GraphRAG"
+
+
 def list_sessions(socket, flow_id, user, collection, limit):
-    """List all GraphRAG sessions by finding questions."""
+    """List all explainability sessions (GraphRAG and Agent) by finding questions."""
     # Query for all triples with predicate = tg:query
     triples = query_triples(
         socket, flow_id, user, collection,
@@ -129,9 +172,12 @@ def list_sessions(socket, flow_id, user, collection, limit):
     for question_id, _, query_text in triples:
         # Get timestamp if available
         timestamp = get_timestamp(socket, flow_id, user, collection, question_id)
+        # Get session type (Agent or GraphRAG)
+        session_type = get_session_type(socket, flow_id, user, collection, question_id)
 
         sessions.append({
             "id": question_id,
+            "type": session_type,
             "question": query_text,
             "time": timestamp,
         })
@@ -154,18 +200,19 @@ def truncate_text(text, max_len=60):
 def print_table(sessions):
     """Print sessions as a table."""
     if not sessions:
-        print("No GraphRAG sessions found.")
+        print("No explainability sessions found.")
         return
 
     rows = []
     for session in sessions:
         rows.append([
             session["id"],
-            truncate_text(session["question"], 50),
+            session.get("type", "Unknown"),
+            truncate_text(session["question"], 45),
             session.get("time", "")
         ])
 
-    headers = ["Session ID", "Question", "Time"]
+    headers = ["Session ID", "Type", "Question", "Time"]
     print(tabulate(rows, headers=headers, tablefmt="simple"))