anywidget-graph 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

anywidget_graph/converters/sparql.py

@@ -0,0 +1,167 @@
+"""Converter for SPARQL query results (RDF triples)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from anywidget_graph.converters.base import GraphData
+
+
+class SPARQLConverter:
+    """Convert SPARQL query results to graph data.
+
+    Handles RDF data from SPARQL endpoints:
+    - SELECT queries with ?s ?p ?o bindings
+    - CONSTRUCT queries returning triples
+    - RDFLib result objects
+
+    The converter treats URIs as node identifiers and predicates as edge labels.
+    Literal values become node properties.
+
+    Parameters
+    ----------
+    subject_var : str
+        Variable name for subjects in SELECT results (default: "s").
+    predicate_var : str
+        Variable name for predicates in SELECT results (default: "p").
+    object_var : str
+        Variable name for objects in SELECT results (default: "o").
+    node_label_predicate : str | None
+        Predicate URI used for node labels (default: rdfs:label).
+        Set to None to disable label extraction.
+
+    Example
+    -------
+    >>> from rdflib import Graph as RDFGraph
+    >>> g = RDFGraph()
+    >>> g.parse("data.ttl")
+    >>> result = g.query("SELECT ?s ?p ?o WHERE { ?s ?p ?o }")
+    >>> converter = SPARQLConverter()
+    >>> data = converter.convert(result)
+    """
+
+    def __init__(
+        self,
+        subject_var: str = "s",
+        predicate_var: str = "p",
+        object_var: str = "o",
+        node_label_predicate: str | None = "http://www.w3.org/2000/01/rdf-schema#label",
+    ) -> None:
+        self.subject_var = subject_var
+        self.predicate_var = predicate_var
+        self.object_var = object_var
+        self.node_label_predicate = node_label_predicate
+
+    def convert(self, result: Any) -> GraphData:
+        """Convert SPARQL result to nodes and edges.
+
+        Parameters
+        ----------
+        result : Any
+            SPARQL query result (e.g., from RDFLib or SPARQLWrapper).
+
+        Returns
+        -------
+        GraphData
+            Dictionary with 'nodes' and 'edges' lists.
+        """
+        nodes: dict[str, dict[str, Any]] = {}
+        edges: list[dict[str, Any]] = []
+        labels: dict[str, str] = {}  # URI -> label mapping
+
+        bindings = list(self._iter_bindings(result))
+
+        # First pass: collect labels
+        if self.node_label_predicate:
+            for binding in bindings:
+                pred = self._get_value(binding, self.predicate_var)
+                if pred == self.node_label_predicate:
+                    subj = self._get_value(binding, self.subject_var)
+                    obj = self._get_value(binding, self.object_var)
+                    if subj and obj:
+                        labels[subj] = obj
+
+        # Second pass: build graph
+        for binding in bindings:
+            subj = self._get_value(binding, self.subject_var)
+            pred = self._get_value(binding, self.predicate_var)
+            obj = self._get_value(binding, self.object_var)
+
+            if not subj or not pred:
+                continue
+
+            # Skip label triples (already processed)
+            if pred == self.node_label_predicate:
+                continue
+
+            # Create subject node
+            if subj not in nodes:
+                nodes[subj] = {
+                    "id": subj,
+                    "label": labels.get(subj, self._extract_local_name(subj)),
+                    "uri": subj,
+                }
+
+            # If object is a URI, create object node and edge
+            if obj and self._is_uri(obj):
+                if obj not in nodes:
+                    nodes[obj] = {
+                        "id": obj,
+                        "label": labels.get(obj, self._extract_local_name(obj)),
+                        "uri": obj,
+                    }
+                edges.append(
+                    {
+                        "source": subj,
+                        "target": obj,
+                        "label": self._extract_local_name(pred),
+                        "predicate": pred,
+                    }
+                )
+            elif obj:
+                # Literal value - add as node property
+                prop_name = self._extract_local_name(pred)
+                nodes[subj][prop_name] = obj
+
+        return {"nodes": list(nodes.values()), "edges": edges}
+
+    def _iter_bindings(self, result: Any):
+        """Iterate over result bindings."""
+        # RDFLib Result
+        if hasattr(result, "bindings"):
+            yield from result.bindings
+        # SPARQLWrapper JSON result
+        elif isinstance(result, dict) and "results" in result:
+            yield from result["results"].get("bindings", [])
+        # Iterable of bindings
+        elif hasattr(result, "__iter__"):
+            yield from result
+
+    def _get_value(self, binding: Any, var: str) -> str:
+        """Extract value from a binding for a variable."""
+        if isinstance(binding, dict):
+            # SPARQLWrapper format: {"var": {"value": "..."}}
+            val = binding.get(var, {})
+            if isinstance(val, dict):
+                return str(val.get("value", ""))
+            return str(val) if val else ""
+        # RDFLib format: binding[var] is an RDF term
+        elif hasattr(binding, "__getitem__"):
+            try:
+                val = binding[var]
+                return str(val) if val else ""
+            except (KeyError, TypeError):
+                return ""
+        return ""
+
+    def _is_uri(self, value: str) -> bool:
+        """Check if a value looks like a URI."""
+        return value.startswith(("http://", "https://", "urn:"))
+
+    def _extract_local_name(self, uri: str) -> str:
+        """Extract local name from URI (part after # or last /)."""
+        if "#" in uri:
+            return uri.split("#")[-1]
+        if "/" in uri:
+            return uri.rsplit("/", 1)[-1]
+        return uri

anywidget_graph/ui/__init__.py

@@ -0,0 +1,19 @@
+"""UI components for anywidget-graph."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = ["get_esm", "get_css"]
+
+_UI_DIR = Path(__file__).parent
+
+
+def get_esm() -> str:
+    """Get the combined ESM JavaScript for the widget."""
+    return (_UI_DIR / "index.js").read_text(encoding="utf-8")
+
+
+def get_css() -> str:
+    """Get the combined CSS styles for the widget."""
+    return (_UI_DIR / "styles.css").read_text(encoding="utf-8")

anywidget_graph/ui/icons.js

@@ -0,0 +1,15 @@
+/**
+ * SVG icons for the graph widget UI.
+ */
+export const ICONS = {
+  play: `<svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><path d="M8 5v14l11-7z"/></svg>`,
+  settings: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="3"/><path d="M12 1v4m0 14v4m11-11h-4M5 12H1m17.36-5.64l-2.83 2.83M9.47 14.53l-2.83 2.83m0-10.72l2.83 2.83m5.06 5.06l2.83 2.83"/></svg>`,
+  close: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M18 6L6 18M6 6l12 12"/></svg>`,
+  chevron: `<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 9l6 6 6-6"/></svg>`,
+  chevronRight: `<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9 18l6-6-6-6"/></svg>`,
+  node: `<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><circle cx="12" cy="12" r="8"/></svg>`,
+  edge: `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M5 12h14m-4-4l4 4-4 4"/></svg>`,
+  property: `<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 7h16M4 12h16M4 17h10"/></svg>`,
+  sidebar: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="18" rx="2"/><path d="M9 3v18"/></svg>`,
+  refresh: `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M23 4v6h-6M1 20v-6h6"/><path d="M3.51 9a9 9 0 0114.85-3.36L23 10M1 14l4.64 4.36A9 9 0 0020.49 15"/></svg>`,
+};

anywidget_graph/ui/index.js

@@ -0,0 +1,199 @@
+/**
+ * Main entry point for the anywidget-graph UI.
+ * Orchestrates all UI components and graph rendering.
+ */
+import Graph from "https://esm.sh/graphology@0.25.4";
+import Sigma from "https://esm.sh/sigma@3.0.0";
+
+import { createToolbar } from "./toolbar.js";
+import { createSchemaPanel } from "./schema.js";
+import { createSettingsPanel } from "./settings.js";
+import { createPropertiesPanel } from "./properties.js";
+import * as neo4jBackend from "./neo4j.js";
+
+/**
+ * Execute a query based on the current backend.
+ */
+async function executeQuery(model) {
+  const backend = model.get("database_backend");
+  const query = model.get("query");
+
+  if (!query.trim()) {
+    model.set("query_error", "Please enter a query");
+    model.save_changes();
+    return;
+  }
+
+  if (backend === "neo4j") {
+    const result = await neo4jBackend.executeQuery(
+      query,
+      model.get("connection_database"),
+      model
+    );
+
+    if (result) {
+      model.set("nodes", result.nodes);
+      model.set("edges", result.edges);
+      model.save_changes();
+    }
+  } else if (backend === "grafeo") {
+    // Trigger Python-side execution
+    model.set("_execute_query", model.get("_execute_query") + 1);
+    model.save_changes();
+  }
+}
+
+/**
+ * Main render function for the anywidget.
+ */
+function render({ model, el }) {
+  const wrapper = document.createElement("div");
+  wrapper.className = "awg-wrapper";
+
+  // Apply dark mode
+  function updateTheme() {
+    wrapper.classList.toggle("awg-dark", model.get("dark_mode"));
+  }
+  updateTheme();
+  model.on("change:dark_mode", updateTheme);
+
+  // Create query executor callback
+  const onExecuteQuery = () => executeQuery(model);
+
+  // Create toolbar if enabled
+  if (model.get("show_toolbar")) {
+    const toolbar = createToolbar(model, wrapper, onExecuteQuery);
+    wrapper.appendChild(toolbar);
+  }
+
+  // Main content area (schema + graph + properties)
+  const content = document.createElement("div");
+  content.className = "awg-content";
+
+  // Create schema sidebar (left) - collapsed by default
+  const schemaSidebar = createSchemaPanel(model, onExecuteQuery);
+  content.appendChild(schemaSidebar);
+
+  // Create graph container
+  const container = document.createElement("div");
+  container.className = "awg-graph-container";
+  container.style.width = model.get("width") + "px";
+  container.style.height = model.get("height") + "px";
+  content.appendChild(container);
+
+  // Create properties panel (right) - collapsed by default
+  const propertiesPanel = createPropertiesPanel(model);
+  content.appendChild(propertiesPanel);
+
+  // Create settings panel if enabled
+  if (model.get("show_settings")) {
+    const settingsPanel = createSettingsPanel(model);
+    content.appendChild(settingsPanel);
+  }
+
+  wrapper.appendChild(content);
+  el.appendChild(wrapper);
+
+  // Initialize Graphology graph
+  const graph = new Graph();
+
+  // Add initial nodes
+  const nodes = model.get("nodes") || [];
+  nodes.forEach((node) => {
+    graph.addNode(node.id, {
+      label: node.label || node.id,
+      x: node.x ?? Math.random() * 100,
+      y: node.y ?? Math.random() * 100,
+      size: node.size || 10,
+      color: node.color || "#6366f1",
+    });
+  });
+
+  // Add initial edges
+  const edges = model.get("edges") || [];
+  edges.forEach((edge) => {
+    graph.addEdge(edge.source, edge.target, {
+      label: edge.label || "",
+      size: edge.size || 2,
+      color: edge.color || "#94a3b8",
+    });
+  });
+
+  // Initialize Sigma renderer
+  const renderer = new Sigma(graph, container, {
+    renderLabels: model.get("show_labels"),
+    renderEdgeLabels: model.get("show_edge_labels"),
+    defaultNodeColor: "#6366f1",
+    defaultEdgeColor: "#94a3b8",
+    labelColor: { color: "#333" },
+    labelSize: 12,
+    labelWeight: "500",
+  });
+
+  // Node click handler
+  renderer.on("clickNode", ({ node }) => {
+    const nodeData = graph.getNodeAttributes(node);
+    model.set("selected_node", { id: node, ...nodeData });
+    model.save_changes();
+  });
+
+  // Edge click handler
+  renderer.on("clickEdge", ({ edge }) => {
+    const edgeData = graph.getEdgeAttributes(edge);
+    const [source, target] = graph.extremities(edge);
+    model.set("selected_edge", { source, target, ...edgeData });
+    model.save_changes();
+  });
+
+  // Stage click (deselect)
+  renderer.on("clickStage", () => {
+    model.set("selected_node", null);
+    model.set("selected_edge", null);
+    model.save_changes();
+  });
+
+  // Update graph when nodes change
+  model.on("change:nodes", () => {
+    graph.clear();
+    const newNodes = model.get("nodes") || [];
+    newNodes.forEach((node) => {
+      graph.addNode(node.id, {
+        label: node.label || node.id,
+        x: node.x ?? Math.random() * 100,
+        y: node.y ?? Math.random() * 100,
+        size: node.size || 10,
+        color: node.color || "#6366f1",
+      });
+    });
+    const newEdges = model.get("edges") || [];
+    newEdges.forEach((edge) => {
+      graph.addEdge(edge.source, edge.target, {
+        label: edge.label || "",
+        size: edge.size || 2,
+        color: edge.color || "#94a3b8",
+      });
+    });
+    renderer.refresh();
+  });
+
+  // Update graph when edges change
+  model.on("change:edges", () => {
+    graph.clearEdges();
+    const newEdges = model.get("edges") || [];
+    newEdges.forEach((edge) => {
+      graph.addEdge(edge.source, edge.target, {
+        label: edge.label || "",
+        size: edge.size || 2,
+        color: edge.color || "#94a3b8",
+      });
+    });
+    renderer.refresh();
+  });
+
+  // Cleanup on destroy
+  return () => {
+    renderer.kill();
+  };
+}
+
+export default { render };

anywidget_graph/ui/neo4j.js

@@ -0,0 +1,193 @@
+/**
+ * Neo4j database connection and query execution (browser-side).
+ */
+import neo4j from "https://cdn.jsdelivr.net/npm/neo4j-driver@5.28.0/lib/browser/neo4j-web.esm.min.js";
+
+let driver = null;
+
+/**
+ * Connect to a Neo4j database.
+ */
+export async function connect(uri, username, password, model) {
+  if (driver) {
+    await driver.close();
+    driver = null;
+  }
+
+  model.set("connection_status", "connecting");
+  model.save_changes();
+
+  try {
+    driver = neo4j.driver(uri, neo4j.auth.basic(username, password));
+    await driver.verifyConnectivity();
+    model.set("connection_status", "connected");
+    model.set("query_error", "");
+    model.save_changes();
+
+    await fetchSchema(model);
+    return true;
+  } catch (error) {
+    model.set("connection_status", "error");
+    model.set("query_error", "Connection failed: " + error.message);
+    model.save_changes();
+    driver = null;
+    return false;
+  }
+}
+
+/**
+ * Disconnect from Neo4j database.
+ */
+export async function disconnect(model) {
+  if (driver) {
+    await driver.close();
+    driver = null;
+  }
+  model.set("connection_status", "disconnected");
+  model.save_changes();
+}
+
+/**
+ * Check if connected to Neo4j.
+ */
+export function isConnected() {
+  return driver !== null;
+}
+
+/**
+ * Fetch database schema (labels and relationship types).
+ */
+export async function fetchSchema(model) {
+  if (!driver) return;
+
+  const database = model.get("connection_database") || "neo4j";
+  const session = driver.session({ database });
+
+  try {
+    // Fetch node labels and their properties
+    const labelsResult = await session.run("CALL db.labels()");
+    const nodeTypes = [];
+
+    for (const record of labelsResult.records) {
+      const label = record.get(0);
+      const propsResult = await session.run(
+        `MATCH (n:\`${label}\`) UNWIND keys(n) AS key RETURN DISTINCT key LIMIT 20`
+      );
+      const properties = propsResult.records.map((r) => r.get(0));
+      nodeTypes.push({ label, properties, count: null });
+    }
+
+    // Fetch relationship types and their properties
+    const relTypesResult = await session.run("CALL db.relationshipTypes()");
+    const edgeTypes = [];
+
+    for (const record of relTypesResult.records) {
+      const type = record.get(0);
+      const propsResult = await session.run(
+        `MATCH ()-[r:\`${type}\`]->() UNWIND keys(r) AS key RETURN DISTINCT key LIMIT 20`
+      );
+      const properties = propsResult.records.map((r) => r.get(0));
+      edgeTypes.push({ type, properties, count: null });
+    }
+
+    model.set("schema_node_types", nodeTypes);
+    model.set("schema_edge_types", edgeTypes);
+    model.save_changes();
+  } catch (error) {
+    console.error("Failed to fetch schema:", error);
+  } finally {
+    await session.close();
+  }
+}
+
+/**
+ * Execute a Cypher query.
+ */
+export async function executeQuery(query, database, model) {
+  if (!driver) {
+    model.set("query_error", "Not connected to database");
+    model.save_changes();
+    return null;
+  }
+
+  model.set("query_running", true);
+  model.set("query_error", "");
+  model.save_changes();
+
+  const session = driver.session({ database: database || "neo4j" });
+
+  try {
+    const result = await session.run(query);
+    model.set("query_running", false);
+    model.save_changes();
+    return processRecords(result.records);
+  } catch (error) {
+    model.set("query_running", false);
+    model.set("query_error", "Query error: " + error.message);
+    model.save_changes();
+    return null;
+  } finally {
+    await session.close();
+  }
+}
+
+/**
+ * Process Neo4j records into nodes and edges.
+ */
+function processRecords(records) {
+  const nodes = new Map();
+  const edges = [];
+
+  for (const record of records) {
+    for (const key of record.keys) {
+      const value = record.get(key);
+      processValue(value, nodes, edges);
+    }
+  }
+
+  return { nodes: Array.from(nodes.values()), edges };
+}
+
+/**
+ * Process a single Neo4j value (node, relationship, path, or array).
+ */
+function processValue(value, nodes, edges) {
+  if (!value) return;
+
+  if (neo4j.isNode(value)) {
+    const nodeId = value.elementId || value.identity.toString();
+    if (!nodes.has(nodeId)) {
+      const props = {};
+      for (const [k, v] of Object.entries(value.properties)) {
+        props[k] = neo4j.isInt(v) ? v.toNumber() : v;
+      }
+      nodes.set(nodeId, {
+        id: nodeId,
+        label: props.name || props.title || value.labels[0] || nodeId,
+        labels: value.labels,
+        ...props,
+      });
+    }
+  } else if (neo4j.isRelationship(value)) {
+    const props = {};
+    for (const [k, v] of Object.entries(value.properties)) {
+      props[k] = neo4j.isInt(v) ? v.toNumber() : v;
+    }
+    edges.push({
+      source: value.startNodeElementId || value.start.toString(),
+      target: value.endNodeElementId || value.end.toString(),
+      label: value.type,
+      ...props,
+    });
+  } else if (neo4j.isPath(value)) {
+    for (const segment of value.segments) {
+      processValue(segment.start, nodes, edges);
+      processValue(segment.end, nodes, edges);
+      processValue(segment.relationship, nodes, edges);
+    }
+  } else if (Array.isArray(value)) {
+    for (const item of value) {
+      processValue(item, nodes, edges);
+    }
+  }
+}