mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-07-09 05:12:12 +02:00
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
This commit is contained in:
Cyber MacGeddon
parent
ed902f132e
commit
6895951d3f
9 changed files with 552 additions and 21 deletions
|
|
@ -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,10 @@ default_collection = 'default'
|
|||
# Predicates
|
||||
TG = "https://trustgraph.ai/ns/"
|
||||
TG_QUERY = TG + "query"
|
||||
TG_AGENT_SESSION = TG + "AgentSession"
|
||||
PROV = "http://www.w3.org/ns/prov#"
|
||||
PROV_STARTED_AT_TIME = PROV + "startedAtTime"
|
||||
RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
|
||||
|
||||
# Retrieval graph
|
||||
RETRIEVAL_GRAPH = "urn:graph:retrieval"
|
||||
|
|
@ -117,8 +119,20 @@ 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)."""
|
||||
triples = query_triples(
|
||||
socket, flow_id, user, collection,
|
||||
s=session_id, p=RDF_TYPE, g=RETRIEVAL_GRAPH
|
||||
)
|
||||
for s, p, o in triples:
|
||||
if o == TG_AGENT_SESSION:
|
||||
return "Agent"
|
||||
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 +143,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 +171,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"))
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,15 @@
|
|||
"""
|
||||
Show full explainability trace for a GraphRAG session.
|
||||
Show full explainability trace for a GraphRAG or Agent session.
|
||||
|
||||
Given a question/session URI, displays the complete cascade:
|
||||
Question -> Exploration -> Focus (edge selection) -> Synthesis (answer).
|
||||
Given a question/session URI, displays the complete trace:
|
||||
- GraphRAG: Question -> Exploration -> Focus (edge selection) -> Synthesis (answer)
|
||||
- Agent: Session -> Iteration(s) (thought/action/observation) -> Final Answer
|
||||
|
||||
The tool auto-detects the trace type based on rdf:type.
|
||||
|
||||
Examples:
|
||||
tg-show-explain-trace -U trustgraph -C default "urn:trustgraph:question:abc123"
|
||||
tg-show-explain-trace -U trustgraph -C default "urn:trustgraph:agent:abc123"
|
||||
tg-show-explain-trace --max-answer 1000 "urn:trustgraph:question:abc123"
|
||||
tg-show-explain-trace --show-provenance "urn:trustgraph:question:abc123"
|
||||
"""
|
||||
|
|
@ -31,10 +35,20 @@ TG_REASONING = TG + "reasoning"
|
|||
TG_CONTENT = TG + "content"
|
||||
TG_DOCUMENT = TG + "document"
|
||||
TG_REIFIES = TG + "reifies"
|
||||
# Agent predicates
|
||||
TG_THOUGHT = TG + "thought"
|
||||
TG_ACTION = TG + "action"
|
||||
TG_ARGUMENTS = TG + "arguments"
|
||||
TG_OBSERVATION = TG + "observation"
|
||||
TG_ANSWER = TG + "answer"
|
||||
TG_AGENT_SESSION = TG + "AgentSession"
|
||||
TG_AGENT_ITERATION = TG + "AgentIteration"
|
||||
TG_AGENT_FINAL = TG + "AgentFinal"
|
||||
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"
|
||||
RDFS_LABEL = "http://www.w3.org/2000/01/rdf-schema#label"
|
||||
|
||||
# Graphs
|
||||
|
|
@ -280,6 +294,153 @@ def format_edge(edge, label_cache=None, socket=None, flow_id=None, user=None, co
|
|||
return f"({s_label}, {p_label}, {o_label})"
|
||||
|
||||
|
||||
def detect_trace_type(socket, flow_id, user, collection, entity_id):
|
||||
"""
|
||||
Detect whether an entity is an agent session or GraphRAG question.
|
||||
|
||||
Returns:
|
||||
"agent" if entity has rdf:type = tg:AgentSession
|
||||
"graphrag" otherwise (default)
|
||||
"""
|
||||
triples = query_triples(
|
||||
socket, flow_id, user, collection,
|
||||
s=entity_id, p=RDF_TYPE, g=RETRIEVAL_GRAPH
|
||||
)
|
||||
for s, p, o in triples:
|
||||
if o == TG_AGENT_SESSION:
|
||||
return "agent"
|
||||
return "graphrag"
|
||||
|
||||
|
||||
def build_agent_trace(socket, flow_id, user, collection, session_id, api=None, max_answer=500):
|
||||
"""Build the full explainability trace for an agent session."""
|
||||
trace = {
|
||||
"session_id": session_id,
|
||||
"type": "agent",
|
||||
"question": None,
|
||||
"time": None,
|
||||
"iterations": [],
|
||||
"final_answer": None,
|
||||
}
|
||||
|
||||
# Get session metadata
|
||||
props = get_node_properties(socket, flow_id, user, collection, session_id)
|
||||
trace["question"] = props.get(TG_QUERY, [None])[0]
|
||||
trace["time"] = props.get(PROV_STARTED_AT_TIME, [None])[0]
|
||||
|
||||
# Find all entities derived from this session (iterations and final)
|
||||
# Start by looking for entities where prov:wasDerivedFrom = session_id
|
||||
current_uri = session_id
|
||||
iteration_num = 1
|
||||
|
||||
while True:
|
||||
# Find entities derived from current
|
||||
derived_ids = find_by_predicate_object(
|
||||
socket, flow_id, user, collection,
|
||||
PROV_WAS_DERIVED_FROM, current_uri
|
||||
)
|
||||
|
||||
if not derived_ids:
|
||||
break
|
||||
|
||||
derived_id = derived_ids[0]
|
||||
derived_props = get_node_properties(socket, flow_id, user, collection, derived_id)
|
||||
|
||||
# Check type
|
||||
types = derived_props.get(RDF_TYPE, [])
|
||||
|
||||
if TG_AGENT_ITERATION in types:
|
||||
iteration = {
|
||||
"id": derived_id,
|
||||
"iteration_num": iteration_num,
|
||||
"thought": derived_props.get(TG_THOUGHT, [None])[0],
|
||||
"action": derived_props.get(TG_ACTION, [None])[0],
|
||||
"arguments": derived_props.get(TG_ARGUMENTS, [None])[0],
|
||||
"observation": derived_props.get(TG_OBSERVATION, [None])[0],
|
||||
}
|
||||
trace["iterations"].append(iteration)
|
||||
current_uri = derived_id
|
||||
iteration_num += 1
|
||||
|
||||
elif TG_AGENT_FINAL in types:
|
||||
answer = derived_props.get(TG_ANSWER, [None])[0]
|
||||
if answer and len(answer) > max_answer:
|
||||
answer = answer[:max_answer] + "... [truncated]"
|
||||
trace["final_answer"] = {
|
||||
"id": derived_id,
|
||||
"answer": answer,
|
||||
}
|
||||
break
|
||||
|
||||
else:
|
||||
# Unknown type, stop traversal
|
||||
break
|
||||
|
||||
return trace
|
||||
|
||||
|
||||
def print_agent_text(trace):
|
||||
"""Print agent trace in text format."""
|
||||
print(f"=== Agent Session: {trace['session_id']} ===")
|
||||
print()
|
||||
|
||||
if trace["question"]:
|
||||
print(f"Question: {trace['question']}")
|
||||
if trace["time"]:
|
||||
print(f"Time: {trace['time']}")
|
||||
print()
|
||||
|
||||
# Iterations
|
||||
print("--- Iterations ---")
|
||||
iterations = trace.get("iterations", [])
|
||||
if iterations:
|
||||
for iteration in iterations:
|
||||
print(f"Iteration {iteration['iteration_num']}:")
|
||||
print(f" Thought: {iteration.get('thought', 'N/A')}")
|
||||
print(f" Action: {iteration.get('action', 'N/A')}")
|
||||
|
||||
args = iteration.get('arguments')
|
||||
if args:
|
||||
# Try to pretty-print JSON arguments
|
||||
try:
|
||||
import json
|
||||
args_obj = json.loads(args)
|
||||
args_str = json.dumps(args_obj, indent=4)
|
||||
# Indent each line
|
||||
args_lines = args_str.split('\n')
|
||||
print(f" Arguments:")
|
||||
for line in args_lines:
|
||||
print(f" {line}")
|
||||
except:
|
||||
print(f" Arguments: {args}")
|
||||
else:
|
||||
print(f" Arguments: N/A")
|
||||
|
||||
obs = iteration.get('observation', 'N/A')
|
||||
if obs and len(obs) > 200:
|
||||
obs = obs[:200] + "... [truncated]"
|
||||
print(f" Observation: {obs}")
|
||||
print()
|
||||
else:
|
||||
print("No iterations recorded")
|
||||
print()
|
||||
|
||||
# Final answer
|
||||
print("--- Final Answer ---")
|
||||
final = trace.get("final_answer")
|
||||
if final and final.get("answer"):
|
||||
print("Answer:")
|
||||
for line in final["answer"].split("\n"):
|
||||
print(f" {line}")
|
||||
else:
|
||||
print("No final answer recorded")
|
||||
|
||||
|
||||
def print_agent_json(trace):
|
||||
"""Print agent trace as JSON."""
|
||||
print(json.dumps(trace, indent=2))
|
||||
|
||||
|
||||
def build_trace(socket, flow_id, user, collection, question_id, api=None, show_provenance=False, max_answer=500):
|
||||
"""Build the full explainability trace for a question."""
|
||||
label_cache = {}
|
||||
|
|
@ -530,21 +691,48 @@ def main():
|
|||
socket = api.socket()
|
||||
|
||||
try:
|
||||
trace = build_trace(
|
||||
# Detect trace type (agent vs graphrag)
|
||||
trace_type = detect_trace_type(
|
||||
socket=socket,
|
||||
flow_id=args.flow_id,
|
||||
user=args.user,
|
||||
collection=args.collection,
|
||||
question_id=args.question_id,
|
||||
api=api,
|
||||
show_provenance=args.show_provenance,
|
||||
max_answer=args.max_answer,
|
||||
entity_id=args.question_id,
|
||||
)
|
||||
|
||||
if args.format == 'json':
|
||||
print_json(trace)
|
||||
if trace_type == "agent":
|
||||
# Build and print agent trace
|
||||
trace = build_agent_trace(
|
||||
socket=socket,
|
||||
flow_id=args.flow_id,
|
||||
user=args.user,
|
||||
collection=args.collection,
|
||||
session_id=args.question_id,
|
||||
api=api,
|
||||
max_answer=args.max_answer,
|
||||
)
|
||||
|
||||
if args.format == 'json':
|
||||
print_agent_json(trace)
|
||||
else:
|
||||
print_agent_text(trace)
|
||||
else:
|
||||
print_text(trace, show_provenance=args.show_provenance)
|
||||
# Build and print GraphRAG trace (existing behavior)
|
||||
trace = build_trace(
|
||||
socket=socket,
|
||||
flow_id=args.flow_id,
|
||||
user=args.user,
|
||||
collection=args.collection,
|
||||
question_id=args.question_id,
|
||||
api=api,
|
||||
show_provenance=args.show_provenance,
|
||||
max_answer=args.max_answer,
|
||||
)
|
||||
|
||||
if args.format == 'json':
|
||||
print_json(trace)
|
||||
else:
|
||||
print_text(trace, show_provenance=args.show_provenance)
|
||||
|
||||
finally:
|
||||
socket.close()
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue