mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 16:36:21 +02:00
7a6197d8c3
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
|
||
|---|---|---|
| .. | ||
| __init__.py | ||
| add_library_document.py | ||
| delete_collection.py | ||
| delete_config_item.py | ||
| delete_flow_blueprint.py | ||
| delete_kg_core.py | ||
| delete_mcp_tool.py | ||
| delete_tool.py | ||
| dump_msgpack.py | ||
| dump_queues.py | ||
| get_config_item.py | ||
| get_document_content.py | ||
| get_flow_blueprint.py | ||
| get_kg_core.py | ||
| graph_to_turtle.py | ||
| init_pulsar_manager.py | ||
| init_trustgraph.py | ||
| invoke_agent.py | ||
| invoke_document_embeddings.py | ||
| invoke_document_rag.py | ||
| invoke_embeddings.py | ||
| invoke_graph_embeddings.py | ||
| invoke_graph_rag.py | ||
| invoke_llm.py | ||
| invoke_mcp_tool.py | ||
| invoke_nlp_query.py | ||
| invoke_prompt.py | ||
| invoke_row_embeddings.py | ||
| invoke_rows_query.py | ||
| invoke_structured_query.py | ||
| list_collections.py | ||
| list_config_items.py | ||
| load_doc_embeds.py | ||
| load_kg_core.py | ||
| load_knowledge.py | ||
| load_sample_documents.py | ||
| load_structured_data.py | ||
| load_turtle.py | ||
| put_config_item.py | ||
| put_flow_blueprint.py | ||
| put_kg_core.py | ||
| remove_library_document.py | ||
| save_doc_embeds.py | ||
| set_collection.py | ||
| set_mcp_tool.py | ||
| set_prompt.py | ||
| set_token_costs.py | ||
| set_tool.py | ||
| show_config.py | ||
| show_flow_blueprints.py | ||
| show_flow_state.py | ||
| show_flows.py | ||
| show_graph.py | ||
| show_kg_cores.py | ||
| show_library_documents.py | ||
| show_library_processing.py | ||
| show_mcp_tools.py | ||
| show_parameter_types.py | ||
| show_processor_state.py | ||
| show_prompts.py | ||
| show_token_costs.py | ||
| show_token_rate.py | ||
| show_tools.py | ||
| start_flow.py | ||
| start_library_processing.py | ||
| stop_flow.py | ||
| stop_library_processing.py | ||
| unload_kg_core.py | ||
| verify_system_status.py | ||