Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
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.mdindex 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 budgetprompt_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.pynew file mode 100644index 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.jsonindex 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.jsonindex 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.tsxnew file mode 100644index 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.tsxindex 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 */}