Visualization¶

The provenance graph can be exported as an interactive HTML page, a Mermaid flowchart, a GraphViz DOT file, or raw JSON.

Interactive HTML¶

store.to_html() returns a self-contained HTML page with an interactive Cytoscape.js graph. Click any node to see its full metadata in the sidebar.

# Open immediately in the default browser
store.open_in_browser()

# Or save to a file
html = store.to_html(title="My Run")
with open("provenance.html", "w") as f:
    f.write(html)

The page loads Cytoscape.js and the dagre layout plugin from CDN, so a network connection is required at render time. The generated file is otherwise completely self-contained and works offline once loaded.

Features¶

Left-to-right dagre layout matching the natural data-flow direction
Color-coded nodes by type (same palette as Mermaid / DOT)
Distinct node shapes per type: barrel for data sources, diamond for model steps, ellipse for final outputs, etc.
Citation key borders — nodes with a registered citation key get a colored border: amber for data sources (d_*), blue for agent outputs (a_*). The key is also appended to the node label as [d_1].
Sidebar legend showing node types and, when citation keys are present, a citation key section with matching border swatches
Click any node to inspect its label, type, citation key (highlighted in blue), agent, run ID, timestamp, and any extra metadata

Mermaid¶

store.to_mermaid() returns a Mermaid flowchart string.

print(store.to_mermaid())

Paste the output into mermaid.live or embed it in a GitHub Markdown file:

```mermaid
flowchart LR
    ...
```

Node colours¶

Node type	Colour
`INPUT`	Blue
`DATA_READ`	Green
`TOOL_CALL`	Orange
`TOOL_RESULT`	Amber
`MODEL_REQUEST`	Purple
`MODEL_RESPONSE`	Violet
`AGENT_RUN`	Dark slate
`FINAL_OUTPUT`	Red

GraphViz DOT¶

store.to_dot() returns a GraphViz DOT string.

dot_src = store.to_dot(graph_name="my_run")
print(dot_src)

Render it with the dot CLI:

echo "$DOT_SRC" | dot -Tsvg -o provenance.svg

Or use the Python graphviz package:

import graphviz
g = graphviz.Source(dot_src)
g.render("provenance", format="svg", view=True)

JSON¶

store.to_json() returns a plain Python dict; store.to_json_str() serialises it to a JSON string.

data = store.to_json()
print(data["nodes"])   # list of node dicts
print(data["edges"])   # list of edge dicts

# Pretty-print
print(store.to_json_str(indent=2))

Schema¶

Node — citation_key is only present when the node has a registered citation key.

{
  "id": "...",
  "type": "data_read",
  "label": "[source] Tool: read_file",
  "agent_name": "summariser",
  "run_id": "...",
  "timestamp": "2024-01-01T00:00:00+00:00",
  "data": { "file_path": "report.txt" },
  "citation_key": "d_1"
}

Edge

{
  "source": "<node_id>",
  "target": "<node_id>",
  "label": "cited_in"
}

Working directly with the graph¶

If none of the built-in formats suit you, the full graph is available as store.graph:

graph = store.graph

for node in graph.nodes.values():
    print(node.id, node.type, node.label)

for edge in graph.edges:
    print(edge.source_id, "→", edge.target_id, f"({edge.label})")

# Ancestor traversal
ancestors = graph.ancestors(some_node_id)

# All source-to-output paths
paths = graph.all_paths_to_sources(output_node_id)