Graph-Native Infrastructure for Context and Accountable AI Systems
Python agent-memoryaiai-governanceai-infrastructureartificial-intelligencecontext-engineeringcontext-graphsdata-engineeringdecision-intelligencedeveloper-toolsexplainable-aigenerative-aigraph-ragknowledge-graphllmontologyprovenancepythonreasoningsemantic-search
feat(explorer): add temporal diff comparison to the Temporal panel
Sameer630547531d8365cb
diff --git a/explorer/src/workspaces/GraphWorkspace/plugins/temporalDiffState.ts b/explorer/src/workspaces/GraphWorkspace/plugins/temporalDiffState.tsnew file mode 100644index 00000000..9e7010ac--- /dev/null+++ b/explorer/src/workspaces/GraphWorkspace/plugins/temporalDiffState.ts@@ -0,0 +1,23 @@+// Fetch wrapper for GET /api/temporal/diff (see semantica/explorer/routes/temporal.py).+// added_nodes are node IDs active at to_time but not at from_time; removed_nodes are the+// inverse. Both are plain node-ID lists (no edge-level diffing), matching the snapshot+// route's active_node_ids shape used elsewhere in this workspace.+export interface TemporalDiffResult {+ from_time: string;+ to_time: string;+ added_nodes: string[];+ removed_nodes: string[];+}++export async function fetchTemporalDiff(+ fromTime: string,+ toTime: string,+ signal?: AbortSignal,+): Promise<TemporalDiffResult> {+ const params = new URLSearchParams({ from_time: fromTime, to_time: toTime });+ const response = await fetch(`/api/temporal/diff?${params}`, { signal });+ if (!response.ok) {+ throw new Error(`Temporal diff request failed with status ${response.status}`);+ }+ return response.json();+}diff --git a/explorer/src/workspaces/GraphWorkspace/plugins/temporalOverlayPlugin.tsx b/explorer/src/workspaces/GraphWorkspace/plugins/temporalOverlayPlugin.tsxindex bf656fc6..1b38921e 100644--- a/explorer/src/workspaces/GraphWorkspace/plugins/temporalOverlayPlugin.tsx+++ b/explorer/src/workspaces/GraphWorkspace/plugins/temporalOverlayPlugin.tsx@@ -1,6 +1,10 @@-import type { CSSProperties } from "react";+import { useEffect, useRef, useState, type CSSProperties } from "react";+import { Loader2 } from "lucide-react";-import type { GraphPlugin } from "./types";+import { graph } from "../../../store/graphStore";+import { GRAPH_THEME } from "../graphTheme";+import { fetchTemporalDiff, type TemporalDiffResult } from "./temporalDiffState";+import type { GraphPlugin, GraphPluginContext } from "./types";const TEMPORAL_PANEL_ID = "temporal-panel";@@ -11,6 +15,182 @@ function formatTemporalLabel(value: Date | null) {return `${value.getFullYear()}/${String(value.getMonth() + 1).padStart(2, "0")}`;}+function isValidDateInput(value: string): boolean {+ return value.trim().length > 0 && !Number.isNaN(new Date(value).getTime());+}++type DiffRequestState =+ | { status: "idle" }+ | { status: "loading" }+ | { status: "error"; message: string }+ | { status: "empty"; result: TemporalDiffResult }+ | { status: "success"; result: TemporalDiffResult };++// Diff highlight colors reuse existing theme tokens rather than introducing new+// hex values: semantic[2] is the codebase's green, dangerText is the one named+// danger/red token already used elsewhere in this workspace (GraphWorkspace.tsx).+const DIFF_ADDED_COLOR = GRAPH_THEME.palette.semantic[2];+const DIFF_REMOVED_COLOR = GRAPH_THEME.ui.control.dangerText;++// Highlighting uses baseColor (the node's fill color), not ringColor/haloColor: those two+// are only read by resolveNodeElementStyle/GraphCanvas's decoration pass for nodes in+// hovered/selected/path visual state (see resolveNodeRingSize, showHalo in graphSceneState.ts+// and the nodesToDecorate set in GraphCanvas.tsx) and are silently discarded by the sigma+// nodeReducer for a node sitting in its default (untouched) state — which is exactly the+// state every diffed node is in here. baseColor is read unconditionally by resolveNodeColor's+// default branch regardless of interaction state or zoom tier, so it is the one attribute+// confirmed to actually render the diff highlight.+function clearDiffHighlight(context: GraphPluginContext, previousColors: Map<string, string | undefined>) {+ previousColors.forEach((color, nodeId) => {+ if (graph.hasNode(nodeId)) {+ graph.setNodeAttribute(nodeId, "baseColor", color);+ }+ });+ context.scene?.requestRender();+}++function applyDiffHighlight(context: GraphPluginContext, result: TemporalDiffResult): Map<string, string | undefined> {+ const previousColors = new Map<string, string | undefined>();+ const paint = (nodeId: string, color: string) => {+ if (graph.hasNode(nodeId)) {+ previousColors.set(nodeId, graph.getNodeAttribute(nodeId, "baseColor"));+ graph.setNodeAttribute(nodeId, "baseColor", color);+ }+ };+ result.added_nodes.forEach((nodeId) => paint(nodeId, DIFF_ADDED_COLOR));+ result.removed_nodes.forEach((nodeId) => paint(nodeId, DIFF_REMOVED_COLOR));+ context.scene?.requestRender();+ return previousColors;+}++function DiffSection({ context }: { context: GraphPluginContext }) {+ const [fromTime, setFromTime] = useState("");+ const [toTime, setToTime] = useState("");+ const [validationMessage, setValidationMessage] = useState<string | null>(null);+ const [requestState, setRequestState] = useState<DiffRequestState>({ status: "idle" });+ const abortRef = useRef<AbortController | null>(null);+ // Maps currently-highlighted node ID -> its baseColor before highlighting, so clearing+ // restores the exact prior value instead of an approximation.+ const previousColorsRef = useRef<Map<string, string | undefined>>(new Map());++ // Cancel any in-flight request and clear stale highlights when the panel unmounts+ // (panel closed) — matches the cancellation pattern used by the snapshot fetch in+ // GraphRuntimeStage.tsx (cancel-on-cleanup) plus AbortController per DecisionWorkspace.tsx.+ useEffect(() => {+ return () => {+ abortRef.current?.abort();+ clearDiffHighlight(context, previousColorsRef.current);+ previousColorsRef.current = new Map();+ };+ // eslint-disable-next-line react-hooks/exhaustive-deps+ }, []);++ const handleCompare = () => {+ if (!fromTime.trim() || !toTime.trim()) {+ setValidationMessage("Both a from and to time are required.");+ return;+ }+ if (!isValidDateInput(fromTime) || !isValidDateInput(toTime)) {+ setValidationMessage("Enter valid ISO datetimes, e.g. 2024-01-01T00:00:00.");+ return;+ }+ if (new Date(fromTime).getTime() >= new Date(toTime).getTime()) {+ setValidationMessage("From time must be before to time.");+ return;+ }+ setValidationMessage(null);++ // Cancel any request already in flight before starting a new one.+ abortRef.current?.abort();+ const controller = new AbortController();+ abortRef.current = controller;++ clearDiffHighlight(context, previousColorsRef.current);+ previousColorsRef.current = new Map();+ setRequestState({ status: "loading" });++ fetchTemporalDiff(fromTime, toTime, controller.signal)+ .then((result) => {+ if (controller.signal.aborted) {+ return;+ }+ if (!result.added_nodes.length && !result.removed_nodes.length) {+ setRequestState({ status: "empty", result });+ return;+ }+ previousColorsRef.current = applyDiffHighlight(context, result);+ setRequestState({ status: "success", result });+ })+ .catch((error: unknown) => {+ if (error instanceof Error && error.name === "AbortError") {+ return;+ }+ setRequestState({+ status: "error",+ message: error instanceof Error ? error.message : "Temporal diff request failed.",+ });+ });+ };++ const isLoading = requestState.status === "loading";++ return (+ <div style={diffSectionStyle}>+ <div style={panelEyebrowStyle}>Compare two points in time</div>+ <div style={diffInputRowStyle}>+ <input+ value={fromTime}+ onChange={(event) => setFromTime(event.target.value)}+ placeholder="From, e.g. 2024-01-01T00:00:00"+ style={diffInputStyle}+ />+ <input+ value={toTime}+ onChange={(event) => setToTime(event.target.value)}+ placeholder="To, e.g. 2025-06-15T00:00:00"+ style={diffInputStyle}+ />+ </div>+ <button+ type="button"+ onClick={handleCompare}+ disabled={isLoading}+ style={{ ...diffActionButtonStyle, opacity: isLoading ? 0.7 : 1 }}+ >+ {isLoading ? <Loader2 size={13} className="animate-spin" style={{ marginRight: 6 }} /> : null}+ {isLoading ? "Comparing…" : "Compare"}+ </button>++ {validationMessage ? <div style={diffValidationStyle}>{validationMessage}</div> : null}++ {requestState.status === "error" ? (+ <div style={diffErrorStyle}>{requestState.message}</div>+ ) : null}++ {requestState.status === "empty" ? (+ <div style={emptyTextStyle}>No changes between these two points.</div>+ ) : null}++ {requestState.status === "success" ? (+ <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>+ <div style={detailRowStyle}>+ <span style={detailLabelStyle}>Added</span>+ <span style={{ ...detailValueStyle, color: DIFF_ADDED_COLOR }}>+ {requestState.result.added_nodes.length.toLocaleString()}+ </span>+ </div>+ <div style={detailRowStyle}>+ <span style={detailLabelStyle}>Removed</span>+ <span style={{ ...detailValueStyle, color: DIFF_REMOVED_COLOR }}>+ {requestState.result.removed_nodes.length.toLocaleString()}+ </span>+ </div>+ </div>+ ) : null}+ </div>+ );+}+export const temporalOverlayPlugin: GraphPlugin = {id: "temporal-overlay",mount: () => {},@@ -80,7 +260,7 @@ export const temporalOverlayPlugin: GraphPlugin = {order: 30,defaultOpen: false,preferredWidth: 320,- preferredHeight: 220,+ preferredHeight: 380,content: (<div style={panelBodyStyle}><div style={panelEyebrowStyle}>Current scrubber state</div>@@ -100,6 +280,7 @@ export const temporalOverlayPlugin: GraphPlugin = {{typeof temporal?.activeNodeCount === "number" ? temporal.activeNodeCount.toLocaleString() : "All"}</span></div>+ <DiffSection context={context} /></div>),};@@ -140,3 +321,62 @@ const detailValueStyle: CSSProperties = {fontSize: 12,fontWeight: 600,};++const diffSectionStyle: CSSProperties = {+ display: "flex",+ flexDirection: "column",+ gap: 8,+ marginTop: 4,+ paddingTop: 10,+ borderTop: "1px solid rgba(255,255,255,0.06)",+};++const diffInputRowStyle: CSSProperties = {+ display: "flex",+ gap: 8,+};++const diffInputStyle: CSSProperties = {+ flex: 1,+ minWidth: 0,+ background: "rgba(5, 7, 10, 0.52)",+ border: "1px solid rgba(211, 205, 190, 0.13)",+ color: "#f3f7fd",+ borderRadius: 12,+ padding: "9px 11px",+ fontSize: 12,+ boxShadow: "inset 0 1px 0 rgba(255,255,255,0.035)",+};++const diffActionButtonStyle: CSSProperties = {+ background: GRAPH_THEME.ui.control.primaryBg,+ color: GRAPH_THEME.ui.control.primaryText,+ border: `1px solid ${GRAPH_THEME.ui.control.primaryBorder}`,+ borderRadius: 12,+ padding: "9px 12px",+ cursor: "pointer",+ fontWeight: 700,+ fontSize: 12,+ display: "inline-flex",+ alignItems: "center",+ justifyContent: "center",+ boxShadow: "inset 0 1px 0 rgba(255,255,255,0.07), 0 10px 24px rgba(0,0,0,0.18)",+};++const diffValidationStyle: CSSProperties = {+ color: GRAPH_THEME.ui.control.dangerText,+ fontSize: 12,+ lineHeight: 1.5,+};++const diffErrorStyle: CSSProperties = {+ color: GRAPH_THEME.ui.control.dangerText,+ fontSize: 12,+ lineHeight: 1.5,+};++const emptyTextStyle: CSSProperties = {+ color: "#8ea4be",+ fontSize: 12,+ lineHeight: 1.5,+};