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

tests/unit/test_query/test_triples_cassandra_query.py

@@ -118,8 +118,8 @@ class TestCassandraQueryProcessor:
 
         # Verify result contains the queried triple
         assert len(result) == 1
-        assert result[0].s.value == 'test_subject'
-        assert result[0].p.value == 'test_predicate'
+        assert result[0].s.iri == 'test_subject'
+        assert result[0].p.iri == 'test_predicate'
         assert result[0].o.value == 'test_object'
 
     def test_processor_initialization_with_defaults(self):
@@ -182,8 +182,8 @@ class TestCassandraQueryProcessor:
 
         mock_tg_instance.get_sp.assert_called_once_with('test_collection', 'test_subject', 'test_predicate', g=None, limit=50)
         assert len(result) == 1
-        assert result[0].s.value == 'test_subject'
-        assert result[0].p.value == 'test_predicate'
+        assert result[0].s.iri == 'test_subject'
+        assert result[0].p.iri == 'test_predicate'
         assert result[0].o.value == 'result_object'
 
     @pytest.mark.asyncio
@@ -219,8 +219,8 @@ class TestCassandraQueryProcessor:
 
         mock_tg_instance.get_s.assert_called_once_with('test_collection', 'test_subject', g=None, limit=25)
         assert len(result) == 1
-        assert result[0].s.value == 'test_subject'
-        assert result[0].p.value == 'result_predicate'
+        assert result[0].s.iri == 'test_subject'
+        assert result[0].p.iri == 'result_predicate'
         assert result[0].o.value == 'result_object'
 
     @pytest.mark.asyncio
@@ -256,8 +256,8 @@ class TestCassandraQueryProcessor:
 
         mock_tg_instance.get_p.assert_called_once_with('test_collection', 'test_predicate', g=None, limit=10)
         assert len(result) == 1
-        assert result[0].s.value == 'result_subject'
-        assert result[0].p.value == 'test_predicate'
+        assert result[0].s.iri == 'result_subject'
+        assert result[0].p.iri == 'test_predicate'
         assert result[0].o.value == 'result_object'
 
     @pytest.mark.asyncio
@@ -293,8 +293,8 @@ class TestCassandraQueryProcessor:
 
         mock_tg_instance.get_o.assert_called_once_with('test_collection', 'test_object', g=None, limit=75)
         assert len(result) == 1
-        assert result[0].s.value == 'result_subject'
-        assert result[0].p.value == 'result_predicate'
+        assert result[0].s.iri == 'result_subject'
+        assert result[0].p.iri == 'result_predicate'
         assert result[0].o.value == 'test_object'
 
     @pytest.mark.asyncio
@@ -331,8 +331,8 @@ class TestCassandraQueryProcessor:
 
         mock_tg_instance.get_all.assert_called_once_with('test_collection', limit=1000)
         assert len(result) == 1
-        assert result[0].s.value == 'all_subject'
-        assert result[0].p.value == 'all_predicate'
+        assert result[0].s.iri == 'all_subject'
+        assert result[0].p.iri == 'all_predicate'
         assert result[0].o.value == 'all_object'
 
     def test_add_args_method(self):
@@ -637,8 +637,8 @@ class TestCassandraQueryPerformanceOptimizations:
         )
 
         assert len(result) == 1
-        assert result[0].s.value == 'result_subject'
-        assert result[0].p.value == 'test_predicate'
+        assert result[0].s.iri == 'result_subject'
+        assert result[0].p.iri == 'test_predicate'
         assert result[0].o.value == 'test_object'
 
     @pytest.mark.asyncio
@@ -678,8 +678,8 @@ class TestCassandraQueryPerformanceOptimizations:
         )
 
         assert len(result) == 1
-        assert result[0].s.value == 'test_subject'
-        assert result[0].p.value == 'result_predicate'
+        assert result[0].s.iri == 'test_subject'
+        assert result[0].p.iri == 'result_predicate'
         assert result[0].o.value == 'test_object'
 
     @pytest.mark.asyncio
@@ -802,7 +802,7 @@ class TestCassandraQueryPerformanceOptimizations:
         # Verify all results were returned
         assert len(result) == 5
         for i, triple in enumerate(result):
-            assert triple.s.value == f'subject_{i}'  # Mock returns literal values
+            assert triple.s.iri == f'subject_{i}'  # Mock returns literal values
             assert triple.p.iri == 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type'
             assert triple.p.type == IRI
             assert triple.o.iri == 'http://example.com/Person'  # URIs use .iri