Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

feat(studio): 3D force-graph view with a document-interrelation projection

FABIOTESS45a9bdc19441
diff --git a/examples/document-privacy/README.md b/examples/document-privacy/README.md
index 493f6772..6098d0c6 100644
--- a/examples/document-privacy/README.md
+++ b/examples/document-privacy/README.md
@@ -50,3 +50,18 @@ chunks = chunk_document(text, doc_id="DOC-042")
for group in pack(chunks): # packs to a context budget
prompt_part = render(group)
```
+
+## provenance.py: light up the Studio's 3D document map
+
+The Studio's 3D view has two projections. With no provenance in the store it
+draws the ontology itself (classes, hierarchy, instances). With
+`?entity prov:wasDerivedFrom ?document` triples present it draws the far more
+interesting one: documents as hubs, entities as bridges between them, and any
+entity typed into disjoint classes by different documents as a red knot
+between the documents that disagree.
+
+```python
+from provenance import emit_provenance
+tail = emit_provenance({"SOP-201": ttl_1, "REF-601": ttl_2})
+# append to the merged store before loading
+```
diff --git a/examples/document-privacy/provenance.py b/examples/document-privacy/provenance.py
new file mode 100644
index 00000000..d2ec5373
--- /dev/null
+++ b/examples/document-privacy/provenance.py
@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Provenance triples for the Studio's 3D document map.
+
+The 3D view projects documents as hubs and entities as the bridges between
+them, which answers "how does information interrelate across this corpus"
+at a glance: shared entities pull documents together, and an entity typed
+into disjoint classes by different documents shows up as a red knot between
+the documents that disagree.
+
+That projection needs one thing the extraction usually has and the merged
+store usually loses: which document asserted each subject. This helper takes
+per-document graphs and emits it.
+
+ from provenance import emit_provenance
+ store_tail = emit_provenance({"SOP-201": ttl_1, "REF-601": ttl_2})
+ # append store_tail to the merged store before loading
+"""
+
+import re
+
+PROV = "<http://www.w3.org/ns/prov#wasDerivedFrom>"
+
+
+def emit_provenance(doc_graphs: dict[str, str], ns_prefix: str = ":") -> str:
+ """One wasDerivedFrom triple per subject per document, plus doc labels.
+
+ `doc_graphs` maps a document id to the Turtle body extracted from it.
+ Subjects are recognised as `:name` at the start of a line, which matches
+ the shape most extraction pipelines emit.
+ """
+ lines: list[str] = []
+ for doc_id, body in doc_graphs.items():
+ doc_node = f"{ns_prefix}DOC_{re.sub(r'[^A-Za-z0-9_]', '_', doc_id)}"
+ lines.append(f'{doc_node} <http://www.w3.org/2000/01/rdf-schema#label> "{doc_id}" .')
+ for subject in sorted(set(re.findall(r"^:(\w+)", body, re.M))):
+ lines.append(f"{ns_prefix}{subject} {PROV} {doc_node} .")
+ return "\n".join(lines) + "\n"
diff --git a/studio/package-lock.json b/studio/package-lock.json
index 6bcb37d1..37eee4aa 100644
--- a/studio/package-lock.json
+++ b/studio/package-lock.json
@@ -18,6 +18,7 @@
"d3": "^7.9.0",
"react": "^19.1.0",
"react-dom": "^19.1.0",
+ "react-force-graph-3d": "^1.29.1",
"react-markdown": "^10.1.0",
"remark-gfm": "^4.0.1",
"tailwindcss": "^4.2.1",
@@ -3158,6 +3159,15 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
+ "node_modules/jerrypick": {
+ "version": "1.1.2",
+ "resolved": "https://registry.npmjs.org/jerrypick/-/jerrypick-1.1.2.tgz",
+ "integrity": "sha512-YKnxXEekXKzhpf7CLYA0A+oDP8V0OhICNCr5lv96FvSsDEmrb0GKM776JgQvHTMjr7DTTPEVv/1Ciaw0uEWzBA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=12"
+ }
+ },
"node_modules/jiti": {
"version": "2.6.1",
"resolved": "https://registry.npmjs.org/jiti/-/jiti-2.6.1.tgz",
@@ -3171,7 +3181,6 @@
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
"integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
- "dev": true,
"license": "MIT"
},
"node_modules/jsesc": {
@@ -3483,6 +3492,18 @@
"url": "https://github.com/sponsors/wooorm"
}
},
+ "node_modules/loose-envify": {
+ "version": "1.4.0",
+ "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
+ "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
+ "license": "MIT",
+ "dependencies": {
+ "js-tokens": "^3.0.0 || ^4.0.0"
+ },
+ "bin": {
+ "loose-envify": "cli.js"
+ }
+ },
"node_modules/lru-cache": {
"version": "5.1.1",
"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz",
@@ -4421,6 +4442,15 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/object-assign": {
+ "version": "4.1.1",
+ "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
+ "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
"node_modules/parse-entities": {
"version": "4.0.2",
"resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz",
@@ -4514,6 +4544,17 @@
"url": "https://opencollective.com/preact"
}
},
+ "node_modules/prop-types": {
+ "version": "15.8.1",
+ "resolved": "https://registry.npmjs.org/prop-types/-/prop-types-15.8.1.tgz",
+ "integrity": "sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==",
+ "license": "MIT",
+ "dependencies": {
+ "loose-envify": "^1.4.0",
+ "object-assign": "^4.1.1",
+ "react-is": "^16.13.1"
+ }
+ },
"node_modules/property-information": {
"version": "7.1.0",
"resolved": "https://registry.npmjs.org/property-information/-/property-information-7.1.0.tgz",
@@ -4545,6 +4586,44 @@
"react": "^19.2.4"
}
},
+ "node_modules/react-force-graph-3d": {
+ "version": "1.29.1",
+ "resolved": "https://registry.npmjs.org/react-force-graph-3d/-/react-force-graph-3d-1.29.1.tgz",
+ "integrity": "sha512-5Vp+PGpYnO+zLwgK2NvNqdXHvsWLrFzpDfJW1vUA1twjo9SPvXqfUYQrnRmAbD+K2tOxkZw1BkbH31l5b4TWHg==",
+ "license": "MIT",
+ "dependencies": {
+ "3d-force-graph": "^1.79",
+ "prop-types": "15",
+ "react-kapsule": "^2.5"
+ },
+ "engines": {
+ "node": ">=12"
+ },
+ "peerDependencies": {
+ "react": "*"
+ }
+ },
+ "node_modules/react-is": {
+ "version": "16.13.1",
+ "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz",
+ "integrity": "sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==",
+ "license": "MIT"
+ },
+ "node_modules/react-kapsule": {
+ "version": "2.6.0",
+ "resolved": "https://registry.npmjs.org/react-kapsule/-/react-kapsule-2.6.0.tgz",
+ "integrity": "sha512-HzLJoYb1n1kfwjXbqFFcRR0EA6oPsJ64tNdDmCSaL/bz2o9wUZRSb0cMe//grLFeF9EVoL4CD/e6ozLyzEv+PQ==",
+ "license": "MIT",
+ "dependencies": {
+ "jerrypick": "^1.1.2"
+ },
+ "engines": {
+ "node": ">=12"
+ },
+ "peerDependencies": {
+ "react": ">=16.13.1"
+ }
+ },
"node_modules/react-markdown": {
"version": "10.1.0",
"resolved": "https://registry.npmjs.org/react-markdown/-/react-markdown-10.1.0.tgz",
diff --git a/studio/package.json b/studio/package.json
index 9e0177f0..56cdd1d4 100644
--- a/studio/package.json
+++ b/studio/package.json
@@ -21,6 +21,7 @@
"d3": "^7.9.0",
"react": "^19.1.0",
"react-dom": "^19.1.0",
+ "react-force-graph-3d": "^1.29.1",
"react-markdown": "^10.1.0",
"remark-gfm": "^4.0.1",
"tailwindcss": "^4.2.1",
diff --git a/studio/src/components/Graph3D.tsx b/studio/src/components/Graph3D.tsx
new file mode 100644
index 00000000..00fffcc0
--- /dev/null
+++ b/studio/src/components/Graph3D.tsx
@@ -0,0 +1,225 @@
+import { useEffect, useRef, useState } from 'react';
+import ForceGraph3D from 'react-force-graph-3d';
+import * as mcp from '../lib/mcp-client';
+
+/**
+ * 3D view of the knowledge graph: classes and individuals as nodes, subclass
+ * and property edges as links. Same store, same queries, different geometry.
+ * The 2D tree stays the analytical view; this one is spatial: clusters and
+ * hubs are visible at a glance, and the partition sits apart from the
+ * document plumbing.
+ */
+
+interface GNode { id: string; name: string; group: string; val: number; }
+interface GLink { source: string; target: string; kind: string; }
+
+const COLORS: Record<string, string> = {
+ Document: '#89b4fa',
+ Individual: '#fab387',
+ conflict: '#f38ba8',
+};
+
+function short(iri: string): string {
+ const h = iri.lastIndexOf('#');
+ return h >= 0 ? iri.slice(h + 1) : iri.slice(iri.lastIndexOf('/') + 1);
+}
+
+const strip = (v: string) =>
+ v.startsWith('<') ? v.slice(1, -1) : v.replace(/^"(.*)"(@[\w-]+)?(\^\^.*)?$/, '$1');
+
+async function rows(q: string): Promise<Array<Record<string, string>>> {
+ try {
+ const raw = await mcp.sparqlQuery(q);
+ return (JSON.parse(raw).results ?? []).map((r: Record<string, string>) => {
+ const o: Record<string, string> = {};
+ for (const [k, v] of Object.entries(r)) o[k] = strip(String(v));
+ return o;
+ });
+ } catch { return []; }
+}
+
+export function Graph3D({ onNodeSelect }: {
+ onNodeSelect: (n: { id: string; label: string; uri: string } | null) => void;
+}) {
+ const [data, setData] = useState<{ nodes: GNode[]; links: GLink[] }>({ nodes: [], links: [] });
+ const fgRef = useRef<{ d3Force: (name: string) => { distance?: (d: (l: GLink) => number) => void; strength?: (v: number) => void } | undefined; zoomToFit: (ms: number, px: number) => void } | null>(null);
+ const framed = useRef(false);
+
+ useEffect(() => {
+ // Pull the constellation together: short leashes on provenance edges,
+ // stronger mutual repulsion only at close range.
+ const fg = fgRef.current;
+ if (!fg || data.nodes.length === 0) return;
+ framed.current = false;
+ fg.d3Force('link')?.distance?.((l: GLink) => (l.kind === 'cooc' ? 55 : l.kind === 'rel' ? 18 : 26));
+ fg.d3Force('charge')?.strength?.(-35);
+ }, [data]);
+ const holder = useRef<HTMLDivElement>(null);
+ const [size, setSize] = useState({ w: 800, h: 600 });
+
+ useEffect(() => {
+ const el = holder.current;
+ if (!el) return;
+ const ro = new ResizeObserver(() => setSize({ w: el.clientWidth, h: el.clientHeight }));
+ ro.observe(el);
+ return () => ro.disconnect();
+ }, []);
+
+ const load = async () => {
+ // The projection that answers "how does information interrelate between
+ // documents": documents as hubs, entities as the bridges between them.
+ // An entity shared by many documents pulls them together spatially; the
+ // contradiction sits visibly between the documents that disagree.
+ const P = 'PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> PREFIX owl: <http://www.w3.org/2002/07/owl#> PREFIX prov: <http://www.w3.org/ns/prov#>';
+ const prov = await rows(`${P} SELECT ?e ?d ?dl ?el WHERE { ?e prov:wasDerivedFrom ?d . ?d rdfs:label ?dl . OPTIONAL { ?e rdfs:label ?el } } LIMIT 2000`);
+ const conflicts = await rows(`${P} SELECT DISTINCT ?s WHERE { ?s a ?a, ?b . FILTER(STR(?a) < STR(?b)) { ?a owl:disjointWith ?b } UNION { ?b owl:disjointWith ?a } }`);
+ const rel = await rows(`${P} SELECT ?s ?o WHERE { ?s ?p ?o . ?o prov:wasDerivedFrom ?x . ?s prov:wasDerivedFrom ?y . FILTER(?p != prov:wasDerivedFrom && isIRI(?o)) } LIMIT 1500`);
+
+ const conflicted = new Set(conflicts.map(r => r.s));
+ const nodes = new Map<string, GNode>();
+ const links: GLink[] = [];
+ const seen = new Set<string>();
+ const docsOf = new Map<string, number>();
+
+ // No provenance in the store: fall back to an ontology projection so the
+ // view works on any loaded graph. Documents-and-entities is the richer
+ // picture, but it needs `?entity prov:wasDerivedFrom ?document` triples
+ // (see examples/document-privacy/provenance.py).
+ if (prov.length === 0) {
+ const classes = await rows(`${P} SELECT ?c ?l WHERE { { ?c a owl:Class } UNION { ?c rdfs:subClassOf ?x } OPTIONAL { ?c rdfs:label ?l } FILTER(!isBlank(?c)) } LIMIT 300`);
+ const subs = await rows(`${P} SELECT ?a ?b WHERE { ?a rdfs:subClassOf ?b . FILTER(!isBlank(?a) && !isBlank(?b)) }`);
+ const inds = await rows(`${P} SELECT ?i ?t ?l WHERE { ?i a ?t . ?t a owl:Class . OPTIONAL { ?i rdfs:label ?l } FILTER(!isBlank(?i)) } LIMIT 300`);
+ for (const r of classes) {
+ if (r.c) nodes.set(r.c, { id: r.c, name: r.l || short(r.c), group: 'Document', val: 3 });
+ }
+ for (const r of subs) {
+ if (nodes.has(r.a) && nodes.has(r.b)) links.push({ source: r.a, target: r.b, kind: 'rel' });
+ }
+ for (const r of inds) {
+ if (!r.i || !nodes.has(r.t)) continue;
+ if (!nodes.has(r.i)) {
+ nodes.set(r.i, {
+ id: r.i, name: r.l || short(r.i),
+ group: conflicted.has(r.i) ? 'conflict' : 'Individual', val: 1,
+ });
+ }
+ links.push({ source: r.i, target: r.t, kind: conflicted.has(r.i) ? 'conflictProv' : 'prov' });
+ }
+ setData({ nodes: [...nodes.values()], links });
+ return;
+ }
+
+ for (const r of prov) {
+ if (!r.e || !r.d) continue;
+ if (!nodes.has(r.d)) nodes.set(r.d, { id: r.d, name: r.dl || short(r.d), group: 'Document', val: 6 });
+ if (!nodes.has(r.e)) {
+ nodes.set(r.e, {
+ id: r.e, name: r.el || short(r.e),
+ group: conflicted.has(r.e) ? 'conflict' : 'Individual', val: 1,
+ });
+ }
+ const k = r.e + '|' + r.d;
+ if (!seen.has(k)) {
+ seen.add(k);
+ links.push({ source: r.e, target: r.d, kind: conflicted.has(r.e) ? 'conflictProv' : 'prov' });
+ docsOf.set(r.e, (docsOf.get(r.e) ?? 0) + 1);
+ }
+ }
+ // entity-to-entity relationships, so structure inside a document shows too
+ for (const r of rel) {
+ if (nodes.has(r.s) && nodes.has(r.o) && r.s !== r.o) {
+ const k = 'rel|' + r.s + '|' + r.o;
+ if (!seen.has(k)) { seen.add(k); links.push({ source: r.s, target: r.o, kind: 'rel' }); }
+ }
+ }
+ for (const n of nodes.values()) {
+ if (n.group !== 'Document') n.val = Math.max(1, Math.min(9, (docsOf.get(n.id) ?? 1) * 1.6));
+ }
+
+ // Prune for shape: sections and hundreds of one-document leaves turn the
+ // layout into spray. Shared entities, conflicted entities and anything in
+ // a relationship stay; singletons are sampled.
+ const inRel = new Set<string>();
+ for (const l of links) if (l.kind === 'rel') { inRel.add(l.source); inRel.add(l.target); }
+ let singletons = 0;
+ const keep = new Set<string>();
+ for (const n of nodes.values()) {
+ const sid = short(n.id);
+ if (n.group === 'Document') { keep.add(n.id); continue; }
+ if (sid.startsWith('SEC_') || sid.startsWith('CLAIM_')) continue;
+ const shared = (docsOf.get(n.id) ?? 0) >= 2;
+ if (n.group === 'conflict' || shared || inRel.has(n.id)) { keep.add(n.id); continue; }
+ if (singletons < 40) { keep.add(n.id); singletons += 1; }
+ }
+ let keptLinks = links.filter(l => keep.has(l.source) && keep.has(l.target));
+
+ // One organism, not islands: documents that assert the same entities get
+ // a co-occurrence edge weighted by how much they share. This is the
+ // GraphRAG shape, and the edge is real: "these documents talk about the
+ // same things".
+ const docEnts = new Map<string, Set<string>>();
+ for (const l of keptLinks) {
+ if (l.kind === 'prov' || l.kind === 'conflictProv') {
+ if (!docEnts.has(l.target)) docEnts.set(l.target, new Set());
+ docEnts.get(l.target)!.add(l.source);
+ }
+ }
+ const docIds = [...docEnts.keys()];
+ for (let a = 0; a < docIds.length; a++) {
+ for (let b = a + 1; b < docIds.length; b++) {
+ const ea = docEnts.get(docIds[a])!, eb = docEnts.get(docIds[b])!;
+ let sharedN = 0;
+ for (const e of ea) if (eb.has(e)) sharedN += 1;
+ if (sharedN > 0) keptLinks.push({ source: docIds[a], target: docIds[b], kind: 'cooc' });
+ }
+ }
+ setData({ nodes: [...nodes.values()].filter(n => keep.has(n.id)), links: keptLinks });
+ };
+
+ useEffect(() => {
+ load();
+ const w = window as unknown as { __refreshGraph?: () => void };
+ const prev = w.__refreshGraph;
+ w.__refreshGraph = () => { prev?.(); load(); };
+ const onRefresh = () => load();
+ window.addEventListener('lineage-refresh', onRefresh);
+ return () => {
+ window.removeEventListener('lineage-refresh', onRefresh);
+ w.__refreshGraph = prev;
+ };
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, []);
+
+ return (
+ <div ref={holder} className="absolute inset-0" style={{ background: '#11111b' }}>
+ {data.nodes.length === 0 ? (
+ <div className="h-full flex items-center justify-center text-sm" style={{ color: '#6c7086' }}>
+ Build the knowledge graph first (Documents panel).
+ </div>
+ ) : (
+ <ForceGraph3D
+ ref={fgRef as never}
+ onEngineStop={() => {
+ if (!framed.current) { framed.current = true; fgRef.current?.zoomToFit(600, 40); }
+ }}
+ cooldownTicks={120}
+ width={size.w}
+ height={size.h}
+ graphData={data}
+ backgroundColor="#11111b"
+ nodeLabel={(n) => `<div style="font-family:sans-serif;font-size:12px">${(n as GNode).name}</div>`}
+ nodeColor={(n) => COLORS[(n as GNode).group] ?? '#a6adc8'}
+ nodeVal={(n) => (n as GNode).val}
+ nodeOpacity={0.9}
+ linkColor={(l) => (l as GLink).kind === 'conflictProv' ? '#f38ba8' : (l as GLink).kind === 'rel' ? '#a6e3a1' : (l as GLink).kind === 'cooc' ? '#313244' : '#45475a'}
+ linkOpacity={0.4}
+ linkWidth={(l) => (l as GLink).kind === 'conflictProv' ? 2 : (l as GLink).kind === 'cooc' ? 0.4 : (l as GLink).kind === 'rel' ? 0.6 : 0.9}
+ onNodeClick={(n) => {
+ const g = n as GNode;
+ onNodeSelect({ id: short(g.id), label: g.name, uri: g.id });
+ }}
+ />
+ )}
+ </div>
+ );
+}
diff --git a/studio/src/components/Layout.tsx b/studio/src/components/Layout.tsx
index c5e458fc..1b37f384 100644
--- a/studio/src/components/Layout.tsx
+++ b/studio/src/components/Layout.tsx
@@ -1,6 +1,7 @@
import { useState, useEffect, useRef } from 'react';
import { useEngine } from '../hooks/useEngine';
import { TreeView } from './TreeView';
+import { Graph3D } from './Graph3D';
import { ChatPanel } from './ChatPanel';
import { PropertyInspector } from './PropertyInspector';
import { LineagePanel } from './LineagePanel';
@@ -10,6 +11,7 @@ type ViewMode = 'tree';
export function Layout() {
const [showChat, setShowChat] = useState(true);
+ const [graphMode, setGraphMode] = useState<'2d' | '3d'>('2d');
const [showInspector, setShowInspector] = useState(false);
const [showLineage, setShowLineage] = useState(false);
const [_viewMode, _setViewMode] = useState<ViewMode>('tree');
@@ -122,6 +124,17 @@ export function Layout() {
<div className="ml-auto flex gap-2">
{/* View mode toggle */}
<div className="w-px mx-1" style={{ background: 'var(--border)' }} />
+ <div className="flex items-center rounded text-xs overflow-hidden"
+ style={{ border: '1px solid var(--border)' }}>
+ {(['2d', '3d'] as const).map(m => (
+ <button key={m} onClick={() => setGraphMode(m)}
+ className="px-2 py-1 uppercase"
+ style={{ background: graphMode === m ? 'var(--accent)' : 'var(--bg-panel)',
+ color: graphMode === m ? 'var(--bg-primary)' : 'var(--text-secondary)' }}>
+ {m}
+ </button>
+ ))}
+ </div>
<button onClick={() => setShowChat(!showChat)}
className="text-xs px-2 py-1 rounded"
style={{ background: showChat ? 'var(--accent)' : 'var(--bg-panel)',
@@ -147,7 +160,9 @@ export function Layout() {
<div className="flex-1 flex overflow-hidden">
{/* Graph canvas */}
<div className="flex-1 relative">
- <TreeView onNodeSelect={setSelectedNode} />
+ {graphMode === '2d'
+ ? <TreeView onNodeSelect={setSelectedNode} />
+ : <Graph3D onNodeSelect={setSelectedNode} />}
</div>
{/* Inspector panel */}