Explainability Using CLI

Description

Use command-line tools to trace GraphRAG answers back to their sources

Difficulty

Intermediate

Duration

20 min

You will need
Goal

Run explainable GraphRAG queries from the CLI, review reasoning traces, and trace edges back to source documents.

This guide covers the same explainability workflow as the Explainability guide, but using command-line tools instead of the Workbench.

New to explainability? Read the Explainability overview first to understand the concepts.

This guide demonstrates:

  • Running GraphRAG queries with inline explainability
  • Listing and reviewing past explainability sessions
  • Viewing full reasoning traces
  • Tracing edges back to source documents
  • Querying provenance data directly

Step 1: Run an Explainable GraphRAG Query

Use the -x flag to enable explainability:

tg-invoke-graph-rag \
  -x \
  -q "What are the key entities involved in Operation Phantom Cargo?" \
  -C intelligence

The answer streams to stdout as normal. Meanwhile, explainability events are reported to stderr as each pipeline stage completes:

  [question] urn:trustgraph:question:a1b2c3...
    Query: What are the key entities involved in Operation Phantom Cargo?
    Time: 2026-03-17T14:30:00Z

  [grounding] urn:trustgraph:grounding:d4e5f6...
    Concepts: 3
      - Operation Phantom Cargo
      - entities
      - involvement

  [exploration] urn:trustgraph:exploration:g7h8i9...
    Edges explored: 47
    Seed entities: 5
      - Operation Phantom Cargo
      - Viktor Sorokin
      - MV Horizon Star
      - Port of Odessa
      - Volkov Industrial Group

  [focus] urn:trustgraph:focus:j0k1l2...
    Focused on 8 edge(s)
      Edge: (Viktor Sorokin, orchestrated, Operation Phantom Cargo)
        Reason: Directly identifies a key entity and their role...
      Edge: (MV Horizon Star, transported, grey arms shipment)
        Reason: Names the vessel involved in the operation...
      ...

  [synthesis] urn:trustgraph:synthesis:m3n4o5...
    Document: ...

The answer then follows, grounded in the selected edges.

Use --debug for additional diagnostic output if events are missing.

Step 2: List Past Sessions

All explainability traces are persistent. List them with:

tg-list-explain-traces -C intelligence

Output:

Session ID                              Type      Question                                        Time
--------------------------------------  --------  ----------------------------------------------  --------------------
urn:trustgraph:question:a1b2c3...       GraphRAG  What are the key entities involved in Oper...   2026-03-17T14:30:00Z
urn:trustgraph:question:x9y8z7...       Agent     Summarise the intelligence findings             2026-03-17T14:25:00Z
urn:trustgraph:question:p5q6r7...       DocRAG    What is the timeline of events?                 2026-03-17T14:20:00Z

Use --format json for machine-readable output, or --limit to control how many sessions are shown.

Step 3: View a Full Trace

Pick a session ID from the listing and view its complete trace:

tg-show-explain-trace \
  -C intelligence \
  "urn:trustgraph:question:a1b2c3..."

This displays the same stages you saw inline, but formatted for review — question, grounding concepts, exploration statistics, focused edges with reasoning, and the synthesised answer.

For JSON output (useful for scripting or analysis):

tg-show-explain-trace \
  --format json \
  -C intelligence \
  "urn:trustgraph:question:a1b2c3..."

Step 4: Trace Edges to Source Documents

Add --show-provenance to follow selected edges back through the extraction provenance chain:

tg-show-explain-trace \
  --show-provenance \
  -C intelligence \
  "urn:trustgraph:question:a1b2c3..."

For each focused edge, this traces the reified triple through urn:graph:source and displays the chain:

  Edge: (Viktor Sorokin, orchestrated, Operation Phantom Cargo)
    Reason: Directly identifies a key entity and their role...
    Provenance: Subgraph abc... -> Chunk def... -> Page 3 -> PHANTOM CARGO

This tells you exactly which text in which document produced each fact.

Step 5: View Extraction Provenance Directly

To see the full extraction hierarchy for a specific document, use tg-show-extraction-provenance:

tg-show-extraction-provenance \
  -C intelligence \
  "urn:trustgraph:doc:phantom-cargo"

This displays a tree:

Document: PHANTOM CARGO
  Page: Page 1
    Chunk: chunk-001
      Subgraph: subgraph-001a (12 edges)
      Subgraph: subgraph-001b (8 edges)
    Chunk: chunk-002
      Subgraph: subgraph-002a (15 edges)
  Page: Page 2
    Chunk: chunk-003
      ...

Add --show-content to include the actual text at each level:

tg-show-extraction-provenance \
  --show-content \
  --max-content 500 \
  -C intelligence \
  "urn:trustgraph:doc:phantom-cargo"

Use --format json for machine-readable output.

Step 6: Query Provenance Data Directly

Since all explainability data is stored as standard RDF triples in named graphs, you can query it directly using tg-show-graph and tg-query-graph:

# View all extraction provenance triples
tg-show-graph -g "urn:graph:source" -C intelligence

# View all query-time traces
tg-show-graph -g "urn:graph:retrieval" -C intelligence

# Find all chunks derived from a specific document
tg-query-graph \
  -p "http://www.w3.org/ns/prov#wasDerivedFrom" \
  -g "urn:graph:source" \
  -C intelligence

# Export provenance as Turtle for external tools
tg-graph-to-turtle -C intelligence > provenance.ttl

Summary

In this guide you:

  • Ran a GraphRAG query with inline explainability (-x)
  • Listed past explainability sessions
  • Reviewed a full reasoning trace
  • Traced edges back to source documents with --show-provenance
  • Viewed extraction provenance hierarchies
  • Queried provenance data directly using graph tools

Next Steps