mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-07-09 13:22:10 +02:00
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
This commit is contained in:
Cyber MacGeddon
parent
6895951d3f
commit
208c2d0cd9
7 changed files with 203 additions and 160 deletions
|
|
@ -6,39 +6,58 @@ Add provenance recording to the React agent loop so agent sessions can be traced
|
|||
|
||||
**Design Decisions:**
|
||||
- Write to `urn:graph:retrieval` (generic explainability graph)
|
||||
- Linear dependency chain for now (iteration N → wasDerivedFrom → iteration N-1)
|
||||
- Linear dependency chain for now (analysis N → wasDerivedFrom → analysis N-1)
|
||||
- Tools are opaque black boxes (record input/output only)
|
||||
- DAG support deferred to future iteration
|
||||
|
||||
## Entity Types
|
||||
|
||||
Both GraphRAG and Agent use PROV-O as the base ontology with TrustGraph-specific subtypes:
|
||||
|
||||
### GraphRAG Types
|
||||
| Entity | PROV-O Type | TG Type | Description |
|
||||
|--------|-------------|---------|-------------|
|
||||
| Question | `prov:Activity` | `tg:Question` | The user's query |
|
||||
| Exploration | `prov:Entity` | `tg:Exploration` | Edges retrieved from knowledge graph |
|
||||
| Focus | `prov:Entity` | `tg:Focus` | Selected edges with reasoning |
|
||||
| Synthesis | `prov:Entity` | `tg:Synthesis` | Final answer |
|
||||
|
||||
### Agent Types
|
||||
| Entity | PROV-O Type | TG Type | Description |
|
||||
|--------|-------------|---------|-------------|
|
||||
| Question | `prov:Activity` | `tg:Question` | The user's query (same as GraphRAG) |
|
||||
| Analysis | `prov:Entity` | `tg:Analysis` | Each think/act/observe cycle |
|
||||
| Conclusion | `prov:Entity` | `tg:Conclusion` | Final answer |
|
||||
|
||||
## Provenance Model
|
||||
|
||||
```
|
||||
AgentSession (urn:trustgraph:agent:{uuid})
|
||||
Question (urn:trustgraph:agent:{uuid})
|
||||
│
|
||||
│ tg:query = "User's question"
|
||||
│ prov:startedAtTime = timestamp
|
||||
│ rdf:type = tg:AgentSession
|
||||
│ rdf:type = prov:Activity, tg:Question
|
||||
│
|
||||
↓ prov:wasGeneratedBy
|
||||
↓ prov:wasDerivedFrom
|
||||
│
|
||||
Iteration1 (urn:trustgraph:agent:{uuid}/i1)
|
||||
Analysis1 (urn:trustgraph:agent:{uuid}/i1)
|
||||
│
|
||||
│ tg:thought = "I need to query the knowledge base..."
|
||||
│ tg:action = "knowledge-query"
|
||||
│ tg:arguments = {"question": "..."}
|
||||
│ tg:observation = "Result from tool..."
|
||||
│ rdf:type = tg:AgentIteration
|
||||
│ rdf:type = prov:Entity, tg:Analysis
|
||||
│
|
||||
↓ prov:wasDerivedFrom
|
||||
│
|
||||
Iteration2 (urn:trustgraph:agent:{uuid}/i2)
|
||||
Analysis2 (urn:trustgraph:agent:{uuid}/i2)
|
||||
│ ...
|
||||
↓ prov:wasDerivedFrom
|
||||
│
|
||||
FinalAnswer (urn:trustgraph:agent:{uuid}/final)
|
||||
Conclusion (urn:trustgraph:agent:{uuid}/final)
|
||||
│
|
||||
│ tg:answer = "The final response..."
|
||||
│ rdf:type = tg:AgentFinal
|
||||
│ rdf:type = prov:Entity, tg:Conclusion
|
||||
```
|
||||
|
||||
## Changes Required
|
||||
|
|
@ -85,23 +104,24 @@ self.register_specification(
|
|||
|
||||
### 3. Provenance Triple Generation
|
||||
|
||||
**Option A:** Add to existing `trustgraph-base/trustgraph/provenance/` module
|
||||
**Option B:** Create agent-specific provenance helpers in the agent module
|
||||
**File:** `trustgraph-base/trustgraph/provenance/agent.py`
|
||||
|
||||
Create helper functions (similar to GraphRAG's `question_triples`, `exploration_triples`, etc.):
|
||||
```python
|
||||
def agent_session_triples(session_uri, query, timestamp):
|
||||
"""Generate triples for agent session start."""
|
||||
"""Generate triples for agent Question."""
|
||||
return [
|
||||
Triple(s=session_uri, p=RDF_TYPE, o=TG_AGENT_SESSION),
|
||||
Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
|
||||
Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
|
||||
Triple(s=session_uri, p=TG_QUERY, o=query),
|
||||
Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
|
||||
]
|
||||
|
||||
def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
|
||||
"""Generate triples for one agent iteration."""
|
||||
"""Generate triples for one Analysis step."""
|
||||
return [
|
||||
Triple(s=iteration_uri, p=RDF_TYPE, o=TG_AGENT_ITERATION),
|
||||
Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
|
||||
Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
|
||||
Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
|
||||
Triple(s=iteration_uri, p=TG_ACTION, o=action),
|
||||
Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
|
||||
|
|
@ -110,127 +130,68 @@ def agent_iteration_triples(iteration_uri, parent_uri, thought, action, argument
|
|||
]
|
||||
|
||||
def agent_final_triples(final_uri, parent_uri, answer):
|
||||
"""Generate triples for agent final answer."""
|
||||
"""Generate triples for Conclusion."""
|
||||
return [
|
||||
Triple(s=final_uri, p=RDF_TYPE, o=TG_AGENT_FINAL),
|
||||
Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
|
||||
Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
|
||||
Triple(s=final_uri, p=TG_ANSWER, o=answer),
|
||||
Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
|
||||
]
|
||||
```
|
||||
|
||||
### 4. Integration in service.py
|
||||
|
||||
**In `agent_request()` method:**
|
||||
|
||||
```python
|
||||
async def agent_request(self, request, respond, next, flow):
|
||||
# Generate or retrieve session ID
|
||||
if not request.session_id:
|
||||
session_id = str(uuid.uuid4())
|
||||
else:
|
||||
session_id = request.session_id
|
||||
|
||||
session_uri = f"urn:trustgraph:agent:{session_id}"
|
||||
iteration_num = len(history) + 1
|
||||
iteration_uri = f"{session_uri}/i{iteration_num}"
|
||||
|
||||
# On first iteration, emit session triples
|
||||
if iteration_num == 1:
|
||||
triples = agent_session_triples(session_uri, request.question, timestamp)
|
||||
await flow("explainability").send(Triples(
|
||||
metadata=Metadata(user=request.user, collection=..., id=session_uri),
|
||||
triples=triples,
|
||||
))
|
||||
|
||||
# ... existing react() call ...
|
||||
|
||||
if isinstance(act, Final):
|
||||
# Emit final answer triples
|
||||
final_uri = f"{session_uri}/final"
|
||||
parent_uri = f"{session_uri}/i{iteration_num - 1}" if iteration_num > 1 else session_uri
|
||||
triples = agent_final_triples(final_uri, parent_uri, act.final)
|
||||
await flow("explainability").send(...)
|
||||
else:
|
||||
# Emit iteration triples
|
||||
parent_uri = f"{session_uri}/i{iteration_num - 1}" if iteration_num > 1 else session_uri
|
||||
triples = agent_iteration_triples(iteration_uri, parent_uri, act.thought, act.name, act.arguments, act.observation)
|
||||
await flow("explainability").send(...)
|
||||
|
||||
# Pass session_id to next iteration
|
||||
r = AgentRequest(
|
||||
...,
|
||||
session_id=session_id,
|
||||
)
|
||||
```
|
||||
|
||||
### 5. Predicate Definitions
|
||||
### 4. Type Definitions
|
||||
|
||||
**File:** `trustgraph-base/trustgraph/provenance/namespaces.py`
|
||||
|
||||
Add new predicates:
|
||||
Add explainability entity types and agent predicates:
|
||||
```python
|
||||
# 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 predicates
|
||||
TG_THOUGHT = TG + "thought"
|
||||
TG_ACTION = TG + "action"
|
||||
TG_ARGUMENTS = TG + "arguments"
|
||||
TG_OBSERVATION = TG + "observation"
|
||||
TG_AGENT_SESSION = TG + "AgentSession"
|
||||
TG_AGENT_ITERATION = TG + "AgentIteration"
|
||||
TG_AGENT_FINAL = TG + "AgentFinal"
|
||||
# TG_QUERY and TG_ANSWER likely already exist
|
||||
TG_ANSWER = TG + "answer"
|
||||
```
|
||||
|
||||
## Files to Modify
|
||||
## Files Modified
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `trustgraph-base/trustgraph/schema/services/agent.py` | Add session_id and collection to AgentRequest |
|
||||
| `trustgraph-base/trustgraph/messaging/translators/agent.py` | Update translator for new fields |
|
||||
| `trustgraph-base/trustgraph/provenance/namespaces.py` | Add agent predicates |
|
||||
| `trustgraph-base/trustgraph/provenance/__init__.py` | Export new predicates |
|
||||
| `trustgraph-base/trustgraph/provenance/namespaces.py` | Add entity types and agent predicates |
|
||||
| `trustgraph-base/trustgraph/provenance/triples.py` | Add TG types to GraphRAG triple builders |
|
||||
| `trustgraph-base/trustgraph/provenance/__init__.py` | Export new types and predicates |
|
||||
| `trustgraph-flow/trustgraph/agent/react/service.py` | Add explainability producer + recording logic |
|
||||
| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Handle agent trace types |
|
||||
| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | List agent sessions alongside GraphRAG |
|
||||
|
||||
## Files to Potentially Create
|
||||
## Files Created
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `trustgraph-base/trustgraph/provenance/agent.py` | Agent-specific triple generators (optional, could inline in service.py) |
|
||||
| `trustgraph-base/trustgraph/provenance/agent.py` | Agent-specific triple generators |
|
||||
|
||||
## CLI Updates Detail
|
||||
## CLI Updates
|
||||
|
||||
**Detection:** Both GraphRAG and Agent Questions have `tg:Question` type. Distinguished by:
|
||||
1. URI pattern: `urn:trustgraph:agent:` vs `urn:trustgraph:question:`
|
||||
2. Derived entities: `tg:Analysis` (agent) vs `tg:Exploration` (GraphRAG)
|
||||
|
||||
**`list_explain_traces.py`:**
|
||||
- Currently queries for `tg:query` predicate to find questions
|
||||
- Agent sessions also use `tg:query`, so should work automatically
|
||||
- May want to add a type indicator column (GraphRAG vs Agent)
|
||||
- Shows Type column (Agent vs GraphRAG)
|
||||
|
||||
**`show_explain_trace.py`:**
|
||||
- Currently expects: question → exploration → focus → synthesis chain
|
||||
- Agent traces have: session → iteration(s) → final chain
|
||||
- Detection: check `rdf:type` of the root entity
|
||||
- `tg:AgentSession` → agent trace rendering
|
||||
- Otherwise → GraphRAG trace rendering (existing)
|
||||
- Agent rendering shows:
|
||||
- Session info (question, time)
|
||||
- Each iteration: thought, action, args, observation
|
||||
- Final answer
|
||||
|
||||
## Design Decisions
|
||||
|
||||
1. **Collection handling:** Add `collection` field to AgentRequest. Agent receives a collection parameter for provenance traces. Tools can access other collections per their config, but decision traces stay in the invoked collection.
|
||||
|
||||
2. **CLI tool updates:** Update existing `tg-show-explain-trace` to detect and handle both GraphRAG and agent trace types.
|
||||
|
||||
## Implementation Order
|
||||
|
||||
0. **Tech Spec:** Write this plan to `docs/tech-specs/agent-explainability.md`
|
||||
1. **Schema:** Add `session_id` and `collection` to AgentRequest + translator
|
||||
2. **Predicates:** Add agent predicates to `namespaces.py`
|
||||
3. **Service:** Add explainability producer to agent service
|
||||
4. **Provenance:** Create/add agent triple generators
|
||||
5. **Integration:** Wire up provenance recording in `agent_request()`
|
||||
6. **CLI:** Update `show_explain_trace.py` to detect and render agent traces
|
||||
7. **Test:** Run agent query and verify trace is recorded and viewable
|
||||
- Auto-detects trace type
|
||||
- Agent rendering shows: Question → Analysis step(s) → Conclusion
|
||||
|
||||
## Backwards Compatibility
|
||||
|
||||
|
|
@ -244,19 +205,16 @@ TG_AGENT_FINAL = TG + "AgentFinal"
|
|||
# Run an agent query
|
||||
tg-invoke-agent -q "What is the capital of France?"
|
||||
|
||||
# Check triples were written
|
||||
tg-query-graph -p "https://trustgraph.ai/ns/query" -g "urn:graph:retrieval"
|
||||
|
||||
# List traces (should show agent sessions)
|
||||
# List traces (should show agent sessions with Type column)
|
||||
tg-list-explain-traces -U trustgraph -C default
|
||||
|
||||
# Show trace (may need CLI updates for agent entity types)
|
||||
# Show agent trace
|
||||
tg-show-explain-trace "urn:trustgraph:agent:xxx"
|
||||
```
|
||||
|
||||
## Future Work (Not This PR)
|
||||
|
||||
- DAG dependencies (when iteration N uses results from multiple prior iterations)
|
||||
- DAG dependencies (when analysis N uses results from multiple prior analyses)
|
||||
- Tool-specific provenance linking (KnowledgeQuery → its GraphRAG trace)
|
||||
- CLI tool enhancements to better display agent traces
|
||||
- Document RAG explainability
|
||||
- Streaming provenance emission (emit as we go, not batch at end)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue