Terminology Rename, and named-graphs for explainability (#682)

Terminology Rename, and named-graphs for explainability data

Changed terminology:
  - session -> question
  - retrieval -> exploration
  - selection -> focus
  - answer -> synthesis

- uris.py: Renamed query_session_uri → question_uri,
  retrieval_uri → exploration_uri, selection_uri → focus_uri,
  answer_uri → synthesis_uri
- triples.py: Renamed corresponding triple generation functions with
  updated labels ("GraphRAG question", "Exploration", "Focus",
  "Synthesis")
- namespaces.py: Added named graph constants GRAPH_DEFAULT,
  GRAPH_SOURCE, GRAPH_RETRIEVAL
- init.py: Updated exports
- graph_rag.py: Updated to use new terminology
- invoke_graph_rag.py: Updated CLI to display new stage names
  (Question, Exploration, Focus, Synthesis)

Query-Time Explainability → Named Graph
- triples.py: Added set_graph() helper function to set named graph
  on triples
- graph_rag.py: All explainability triples now use GRAPH_RETRIEVAL
  named graph
- rag.py: Explainability triples stored in user's collection (not
  separate collection) with named graph

Extraction Provenance → Named Graph
- relationships/extract.py: Provenance triples use GRAPH_SOURCE
  named graph
- definitions/extract.py: Provenance triples use GRAPH_SOURCE
  named graph
- chunker.py: Provenance triples use GRAPH_SOURCE named graph
- pdf_decoder.py: Provenance triples use GRAPH_SOURCE named graph

CLI Updates
- show_graph.py: Added -g/--graph option to filter by named graph and
  --show-graph to display graph column

Also:
- Fix knowledge core schemas
This commit is contained in:
cybermaggedon 2026-03-10 14:35:21 +00:00 committed by GitHub
parent 57eda65674
commit e1bc4c04a4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
17 changed files with 279 additions and 180 deletions

View file

@ -65,59 +65,65 @@ def agent_uri(component_name: str) -> str:
# Query-time provenance URIs
# These URIs use the urn:trustgraph: namespace to distinguish query-time
# provenance from extraction-time provenance (which uses https://trustgraph.ai/)
#
# Terminology:
# Question - What was asked, the anchor for everything
# Exploration - Casting wide, what do we know about this space
# Focus - Closing down, what's actually relevant here
# Synthesis - Weaving the relevant pieces into an answer
def query_session_uri(session_id: str = None) -> str:
def question_uri(session_id: str = None) -> str:
"""
Generate URI for a query session activity.
Generate URI for a question activity.
Args:
session_id: Optional UUID string. Auto-generates if not provided.
Returns:
URN in format: urn:trustgraph:session:{uuid}
URN in format: urn:trustgraph:question:{uuid}
"""
if session_id is None:
session_id = str(uuid.uuid4())
return f"urn:trustgraph:session:{session_id}"
return f"urn:trustgraph:question:{session_id}"
def retrieval_uri(session_id: str) -> str:
def exploration_uri(session_id: str) -> str:
"""
Generate URI for a retrieval entity (edges retrieved from subgraph).
Generate URI for an exploration entity (edges retrieved from subgraph).
Args:
session_id: The session UUID (same as query_session_uri).
session_id: The session UUID (same as question_uri).
Returns:
URN in format: urn:trustgraph:prov:retrieval:{uuid}
URN in format: urn:trustgraph:prov:exploration:{uuid}
"""
return f"urn:trustgraph:prov:retrieval:{session_id}"
return f"urn:trustgraph:prov:exploration:{session_id}"
def selection_uri(session_id: str) -> str:
def focus_uri(session_id: str) -> str:
"""
Generate URI for a selection entity (selected edges with reasoning).
Generate URI for a focus entity (selected edges with reasoning).
Args:
session_id: The session UUID (same as query_session_uri).
session_id: The session UUID (same as question_uri).
Returns:
URN in format: urn:trustgraph:prov:selection:{uuid}
URN in format: urn:trustgraph:prov:focus:{uuid}
"""
return f"urn:trustgraph:prov:selection:{session_id}"
return f"urn:trustgraph:prov:focus:{session_id}"
def answer_uri(session_id: str) -> str:
def synthesis_uri(session_id: str) -> str:
"""
Generate URI for an answer entity (final synthesis text).
Generate URI for a synthesis entity (final answer text).
Args:
session_id: The session UUID (same as query_session_uri).
session_id: The session UUID (same as question_uri).
Returns:
URN in format: urn:trustgraph:prov:answer:{uuid}
URN in format: urn:trustgraph:prov:synthesis:{uuid}
"""
return f"urn:trustgraph:prov:answer:{session_id}"
return f"urn:trustgraph:prov:synthesis:{session_id}"
def edge_selection_uri(session_id: str, edge_index: int) -> str: