mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-30 10:56:23 +02:00
312174eb88
* 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
|
||
|---|---|---|
| .. | ||
| __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 | ||
| list_explain_traces.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 | ||
| query_graph.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_document_hierarchy.py | ||
| show_explain_trace.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 | ||