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

anywidget_graph/widget.py

@@ -8,1624 +8,93 @@ import anywidget
 import traitlets
 from traitlets import observe
 
+from anywidget_graph.backends import DatabaseBackend
+from anywidget_graph.backends.grafeo import GrafeoBackend
+from anywidget_graph.ui import get_css, get_esm
+
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-_ESM = r"""
-import Graph from "https://esm.sh/graphology@0.25.4";
-import Sigma from "https://esm.sh/sigma@3.0.0";
-import neo4j from "https://cdn.jsdelivr.net/npm/neo4j-driver@5.28.0/lib/browser/neo4j-web.esm.min.js";
-
-// === CONSTANTS ===
-const QUERY_LANGUAGES = [
-  { id: "cypher", name: "Cypher", enabled: true },
-  { id: "gql", name: "GQL", enabled: false },
-  { id: "sparql", name: "SPARQL", enabled: false },
-  { id: "gremlin", name: "Gremlin", enabled: false },
-  { id: "graphql", name: "GraphQL", enabled: false },
-];
-
-const BACKENDS = [
-  { id: "neo4j", name: "Neo4j" },
-  { id: "grafeo", name: "Grafeo" },
-];
-
-// === SVG ICONS ===
-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>`,
-};
-
-// === DATABASE CONNECTION ===
-let driver = null;
-
-async function connectNeo4j(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();
-
-    // Fetch schema after successful connection
-    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;
-  }
-}
-
-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);
-      // Get properties for this label
-      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);
-      // Get properties for this relationship type
-      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();
-  }
-}
-
-async function disconnectNeo4j(model) {
-  if (driver) {
-    await driver.close();
-    driver = null;
-  }
-  model.set("connection_status", "disconnected");
-  model.save_changes();
-}
-
-async function executeNeo4jQuery(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 processNeo4jRecords(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();
-  }
-}
-
-function processNeo4jRecords(records) {
-  const nodes = new Map();
-  const edges = [];
-
-  for (const record of records) {
-    for (const key of record.keys) {
-      const value = record.get(key);
-      processNeo4jValue(value, nodes, edges);
-    }
-  }
-
-  return { nodes: Array.from(nodes.values()), edges };
-}
-
-function processNeo4jValue(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) {
-      processNeo4jValue(segment.start, nodes, edges);
-      processNeo4jValue(segment.end, nodes, edges);
-      processNeo4jValue(segment.relationship, nodes, edges);
-    }
-  } else if (Array.isArray(value)) {
-    for (const item of value) {
-      processNeo4jValue(item, nodes, edges);
-    }
-  }
-}
-
-// === UI COMPONENTS ===
-function createToolbar(model, wrapper) {
-  const toolbar = document.createElement("div");
-  toolbar.className = "awg-toolbar";
-
-  // Schema sidebar toggle (left)
-  const schemaBtn = document.createElement("button");
-  schemaBtn.className = "awg-btn";
-  schemaBtn.innerHTML = ICONS.sidebar;
-  schemaBtn.title = "Toggle schema browser";
-  schemaBtn.addEventListener("click", () => toggleSchemaPanel(wrapper));
-  toolbar.appendChild(schemaBtn);
-
-  // Query container (collapsible input)
-  if (model.get("show_query_input")) {
-    const queryContainer = document.createElement("div");
-    queryContainer.className = "awg-query-container";
-
-    const queryInput = document.createElement("input");
-    queryInput.type = "text";
-    queryInput.className = "awg-query-input";
-    queryInput.placeholder = "Enter query (e.g., MATCH (n) RETURN n LIMIT 25)";
-    queryInput.value = model.get("query") || "";
-
-    queryInput.addEventListener("input", (e) => {
-      model.set("query", e.target.value);
-      model.save_changes();
-    });
-
-    queryInput.addEventListener("keydown", (e) => {
-      if (e.key === "Enter" && !e.shiftKey) {
-        e.preventDefault();
-        executeQuery(model);
-      }
-    });
-
-    model.on("change:query", () => {
-      if (queryInput.value !== model.get("query")) {
-        queryInput.value = model.get("query") || "";
-      }
-    });
-
-    queryContainer.appendChild(queryInput);
-
-    // Play button
-    const playBtn = document.createElement("button");
-    playBtn.className = "awg-btn awg-btn-primary";
-    playBtn.innerHTML = ICONS.play;
-    playBtn.title = "Run query";
-    playBtn.addEventListener("click", () => executeQuery(model));
-
-    model.on("change:query_running", () => {
-      playBtn.disabled = model.get("query_running");
-      playBtn.innerHTML = model.get("query_running")
-        ? '<span class="awg-spinner"></span>'
-        : ICONS.play;
-    });
-
-    queryContainer.appendChild(playBtn);
-    toolbar.appendChild(queryContainer);
-  }
-
-  // Settings button
-  if (model.get("show_settings")) {
-    const settingsBtn = document.createElement("button");
-    settingsBtn.className = "awg-btn";
-    settingsBtn.innerHTML = ICONS.settings;
-    settingsBtn.title = "Connection settings";
-
-    // Status dot
-    const statusDot = document.createElement("span");
-    statusDot.className = "awg-status-dot";
-    updateStatusDot(statusDot, model.get("connection_status"));
-    settingsBtn.appendChild(statusDot);
-
-    model.on("change:connection_status", () => {
-      updateStatusDot(statusDot, model.get("connection_status"));
-    });
-
-    settingsBtn.addEventListener("click", () => {
-      toggleSettingsPanel(wrapper);
-    });
-
-    toolbar.appendChild(settingsBtn);
-  }
-
-  // Properties panel toggle (right)
-  const propsBtn = document.createElement("button");
-  propsBtn.className = "awg-btn";
-  propsBtn.innerHTML = ICONS.property;
-  propsBtn.title = "Toggle properties panel";
-  propsBtn.addEventListener("click", () => togglePropertiesPanel(wrapper));
-  toolbar.appendChild(propsBtn);
-
-  return toolbar;
-}
-
-function updateStatusDot(dot, status) {
-  dot.className = "awg-status-dot awg-status-" + status;
-}
-
-function toggleSettingsPanel(wrapper) {
-  const panel = wrapper.querySelector(".awg-settings-panel");
-  if (panel) {
-    panel.classList.toggle("awg-panel-open");
-  }
-}
-
-function toggleSchemaPanel(wrapper) {
-  const panel = wrapper.querySelector(".awg-schema-panel");
-  if (panel) {
-    panel.classList.toggle("awg-panel-open");
-  }
-}
-
-function createSchemaSidebar(model) {
-  const panel = document.createElement("div");
-  panel.className = "awg-schema-panel";
-
-  // Header
-  const header = document.createElement("div");
-  header.className = "awg-panel-header";
-  header.innerHTML = `<span>Schema</span>`;
-
-  const refreshBtn = document.createElement("button");
-  refreshBtn.className = "awg-btn awg-btn-icon awg-btn-sm";
-  refreshBtn.innerHTML = ICONS.refresh;
-  refreshBtn.title = "Refresh schema";
-  refreshBtn.addEventListener("click", () => fetchSchema(model));
-  header.appendChild(refreshBtn);
-
-  panel.appendChild(header);
-
-  // Content
-  const content = document.createElement("div");
-  content.className = "awg-schema-content";
-
-  function renderSchema() {
-    content.innerHTML = "";
-
-    const nodeTypes = model.get("schema_node_types") || [];
-    const edgeTypes = model.get("schema_edge_types") || [];
-
-    if (nodeTypes.length === 0 && edgeTypes.length === 0) {
-      const empty = document.createElement("div");
-      empty.className = "awg-schema-empty";
-      empty.textContent = "Connect to load schema";
-      content.appendChild(empty);
-      return;
-    }
-
-    // Node types section
-    if (nodeTypes.length > 0) {
-      const nodeSection = document.createElement("div");
-      nodeSection.className = "awg-schema-section";
-
-      const nodeHeader = document.createElement("div");
-      nodeHeader.className = "awg-schema-section-header";
-      nodeHeader.innerHTML = `${ICONS.node} <span>Node Labels</span>`;
-      nodeSection.appendChild(nodeHeader);
-
-      nodeTypes.forEach(({ label, properties }) => {
-        const item = createSchemaItem(label, properties, "node", model);
-        nodeSection.appendChild(item);
-      });
-
-      content.appendChild(nodeSection);
-    }
-
-    // Edge types section
-    if (edgeTypes.length > 0) {
-      const edgeSection = document.createElement("div");
-      edgeSection.className = "awg-schema-section";
-
-      const edgeHeader = document.createElement("div");
-      edgeHeader.className = "awg-schema-section-header";
-      edgeHeader.innerHTML = `${ICONS.edge} <span>Relationships</span>`;
-      edgeSection.appendChild(edgeHeader);
-
-      edgeTypes.forEach(({ type, properties }) => {
-        const item = createSchemaItem(type, properties, "edge", model);
-        edgeSection.appendChild(item);
-      });
-
-      content.appendChild(edgeSection);
-    }
-  }
-
-  model.on("change:schema_node_types", renderSchema);
-  model.on("change:schema_edge_types", renderSchema);
-  renderSchema();
-
-  panel.appendChild(content);
-  return panel;
-}
-
-function createSchemaItem(name, properties, type, model) {
-  const item = document.createElement("div");
-  item.className = "awg-schema-item";
-
-  const itemHeader = document.createElement("div");
-  itemHeader.className = "awg-schema-item-header";
-
-  const expandBtn = document.createElement("span");
-  expandBtn.className = "awg-schema-expand";
-  expandBtn.innerHTML = ICONS.chevronRight;
-
-  const nameSpan = document.createElement("span");
-  nameSpan.className = "awg-schema-name";
-  nameSpan.textContent = name;
-
-  itemHeader.appendChild(expandBtn);
-  itemHeader.appendChild(nameSpan);
-
-  // Click on name to query
-  nameSpan.addEventListener("click", (e) => {
-    e.stopPropagation();
-    let query;
-    if (type === "node") {
-      query = `MATCH (n:\`${name}\`) RETURN n LIMIT 25`;
-    } else {
-      query = `MATCH (a)-[r:\`${name}\`]->(b) RETURN a, r, b LIMIT 25`;
-    }
-    model.set("query", query);
-    model.save_changes();
-    executeQuery(model);
-  });
-
-  // Properties list (collapsed by default)
-  const propsList = document.createElement("div");
-  propsList.className = "awg-schema-props";
-
-  if (properties && properties.length > 0) {
-    properties.forEach(prop => {
-      const propItem = document.createElement("div");
-      propItem.className = "awg-schema-prop";
-      propItem.innerHTML = `${ICONS.property} <span>${prop}</span>`;
-
-      // Click on property to query with that property
-      propItem.addEventListener("click", (e) => {
-        e.stopPropagation();
-        let query;
-        if (type === "node") {
-          query = `MATCH (n:\`${name}\`) RETURN n.\`${prop}\` AS ${prop}, n LIMIT 25`;
-        } else {
-          query = `MATCH (a)-[r:\`${name}\`]->(b) RETURN r.\`${prop}\` AS ${prop}, a, r, b LIMIT 25`;
-        }
-        model.set("query", query);
-        model.save_changes();
-        executeQuery(model);
-      });
-
-      propsList.appendChild(propItem);
-    });
-  } else {
-    const noProp = document.createElement("div");
-    noProp.className = "awg-schema-prop awg-schema-prop-empty";
-    noProp.textContent = "No properties";
-    propsList.appendChild(noProp);
-  }
-
-  item.appendChild(itemHeader);
-  item.appendChild(propsList);
-
-  // Toggle expand/collapse
-  itemHeader.addEventListener("click", () => {
-    item.classList.toggle("awg-schema-item-expanded");
-  });
-
-  return item;
-}
-
-function createSettingsPanel(model) {
-  const panel = document.createElement("div");
-  panel.className = "awg-settings-panel";
-
-  // Header
-  const header = document.createElement("div");
-  header.className = "awg-panel-header";
-  header.innerHTML = "<span>Settings</span>";
-  panel.appendChild(header);
-
-  // Form
-  const form = document.createElement("div");
-  form.className = "awg-panel-form";
-
-  // Dark mode toggle
-  form.appendChild(createFormGroup("Theme", () => {
-    const toggle = document.createElement("label");
-    toggle.className = "awg-toggle";
-    const checkbox = document.createElement("input");
-    checkbox.type = "checkbox";
-    checkbox.checked = model.get("dark_mode");
-    checkbox.addEventListener("change", (e) => {
-      model.set("dark_mode", e.target.checked);
-      model.save_changes();
-    });
-    model.on("change:dark_mode", () => {
-      checkbox.checked = model.get("dark_mode");
-    });
-    const slider = document.createElement("span");
-    slider.className = "awg-toggle-slider";
-    const label = document.createElement("span");
-    label.className = "awg-toggle-label";
-    label.textContent = "Dark mode";
-    toggle.appendChild(checkbox);
-    toggle.appendChild(slider);
-    toggle.appendChild(label);
-    return toggle;
-  }));
-
-  // Backend selector
-  form.appendChild(createFormGroup("Backend", () => {
-    const select = document.createElement("select");
-    select.className = "awg-select";
-    BACKENDS.forEach(b => {
-      const opt = document.createElement("option");
-      opt.value = b.id;
-      opt.textContent = b.name;
-      opt.selected = model.get("database_backend") === b.id;
-      select.appendChild(opt);
-    });
-    select.addEventListener("change", (e) => {
-      model.set("database_backend", e.target.value);
-      model.save_changes();
-      updateFormVisibility();
-    });
-    return select;
-  }));
-
-  // Neo4j fields container
-  const neo4jFields = document.createElement("div");
-  neo4jFields.className = "awg-neo4j-fields";
-
-  // URI
-  neo4jFields.appendChild(createFormGroup("URI", () => {
-    const input = document.createElement("input");
-    input.type = "text";
-    input.className = "awg-input";
-    input.placeholder = "neo4j+s://localhost:7687";
-    input.value = model.get("connection_uri") || "";
-    input.addEventListener("input", (e) => {
-      model.set("connection_uri", e.target.value);
-      model.save_changes();
-    });
-    return input;
-  }));
-
-  // Username
-  neo4jFields.appendChild(createFormGroup("Username", () => {
-    const input = document.createElement("input");
-    input.type = "text";
-    input.className = "awg-input";
-    input.placeholder = "neo4j";
-    input.value = model.get("connection_username") || "";
-    input.addEventListener("input", (e) => {
-      model.set("connection_username", e.target.value);
-      model.save_changes();
-    });
-    return input;
-  }));
-
-  // Password
-  neo4jFields.appendChild(createFormGroup("Password", () => {
-    const input = document.createElement("input");
-    input.type = "password";
-    input.className = "awg-input";
-    input.value = model.get("connection_password") || "";
-    input.addEventListener("input", (e) => {
-      model.set("connection_password", e.target.value);
-      model.save_changes();
-    });
-    return input;
-  }));
-
-  form.appendChild(neo4jFields);
-
-  // Database name
-  form.appendChild(createFormGroup("Database", () => {
-    const input = document.createElement("input");
-    input.type = "text";
-    input.className = "awg-input";
-    input.placeholder = "neo4j";
-    input.value = model.get("connection_database") || "neo4j";
-    input.addEventListener("input", (e) => {
-      model.set("connection_database", e.target.value);
-      model.save_changes();
-    });
-    return input;
-  }));
-
-  // Query language
-  form.appendChild(createFormGroup("Language", () => {
-    const select = document.createElement("select");
-    select.className = "awg-select";
-    QUERY_LANGUAGES.forEach(lang => {
-      const opt = document.createElement("option");
-      opt.value = lang.id;
-      opt.textContent = lang.name;
-      opt.disabled = !lang.enabled;
-      opt.selected = model.get("query_language") === lang.id;
-      select.appendChild(opt);
-    });
-    select.addEventListener("change", (e) => {
-      model.set("query_language", e.target.value);
-      model.save_changes();
-    });
-    return select;
-  }));
-
-  panel.appendChild(form);
-
-  // Connect button
-  const actions = document.createElement("div");
-  actions.className = "awg-panel-actions";
-
-  const connectBtn = document.createElement("button");
-  connectBtn.className = "awg-btn awg-btn-primary awg-btn-full";
-
-  const statusIndicator = document.createElement("div");
-  statusIndicator.className = "awg-connection-status";
-
-  function updateConnectButton() {
-    const status = model.get("connection_status");
-    const backend = model.get("database_backend");
-
-    if (backend === "grafeo") {
-      connectBtn.textContent = "Python Backend";
-      connectBtn.disabled = true;
-      statusIndicator.innerHTML = '<span class="awg-status-dot-inline awg-status-connected"></span> Grafeo';
-    } else if (status === "connected") {
-      connectBtn.textContent = "Disconnect";
-      connectBtn.disabled = false;
-      statusIndicator.innerHTML = '<span class="awg-status-dot-inline awg-status-connected"></span> Connected';
-    } else if (status === "connecting") {
-      connectBtn.textContent = "Connecting...";
-      connectBtn.disabled = true;
-      statusIndicator.innerHTML = '<span class="awg-status-dot-inline awg-status-connecting"></span> Connecting';
-    } else if (status === "error") {
-      connectBtn.textContent = "Retry";
-      connectBtn.disabled = false;
-      statusIndicator.innerHTML = '<span class="awg-status-dot-inline awg-status-error"></span> Error';
-    } else {
-      connectBtn.textContent = "Connect";
-      connectBtn.disabled = false;
-      statusIndicator.innerHTML = '<span class="awg-status-dot-inline awg-status-disconnected"></span> Disconnected';
-    }
-  }
-
-  function updateFormVisibility() {
-    const backend = model.get("database_backend");
-    neo4jFields.style.display = backend === "neo4j" ? "block" : "none";
-    updateConnectButton();
-  }
-
-  connectBtn.addEventListener("click", async () => {
-    const backend = model.get("database_backend");
-    if (backend !== "neo4j") return;
-
-    const status = model.get("connection_status");
-    if (status === "connected") {
-      await disconnectNeo4j(model);
-    } else {
-      await connectNeo4j(
-        model.get("connection_uri"),
-        model.get("connection_username"),
-        model.get("connection_password"),
-        model
-      );
-    }
-  });
-
-  model.on("change:connection_status", updateConnectButton);
-  model.on("change:database_backend", updateFormVisibility);
-
-  actions.appendChild(statusIndicator);
-  actions.appendChild(connectBtn);
-  panel.appendChild(actions);
-
-  // Error display
-  const errorDiv = document.createElement("div");
-  errorDiv.className = "awg-panel-error";
-  function updateError() {
-    const err = model.get("query_error");
-    errorDiv.textContent = err || "";
-    errorDiv.style.display = err ? "block" : "none";
-  }
-  model.on("change:query_error", updateError);
-  updateError();
-  panel.appendChild(errorDiv);
-
-  // Initialize
-  updateFormVisibility();
-
-  return panel;
-}
-
-function createFormGroup(label, inputFn) {
-  const group = document.createElement("div");
-  group.className = "awg-form-group";
-
-  const labelEl = document.createElement("label");
-  labelEl.className = "awg-label";
-  labelEl.textContent = label;
-  group.appendChild(labelEl);
-
-  group.appendChild(inputFn());
-  return group;
-}
-
-function createPropertiesPanel(model) {
-  const panel = document.createElement("div");
-  panel.className = "awg-properties-panel";
-
-  // Header
-  const header = document.createElement("div");
-  header.className = "awg-panel-header";
-  header.innerHTML = "<span>Properties</span>";
-  panel.appendChild(header);
-
-  // Content
-  const content = document.createElement("div");
-  content.className = "awg-properties-content";
-
-  function renderProperties() {
-    content.innerHTML = "";
-
-    const selectedNode = model.get("selected_node");
-    const selectedEdge = model.get("selected_edge");
-
-    if (!selectedNode && !selectedEdge) {
-      const empty = document.createElement("div");
-      empty.className = "awg-properties-empty";
-      empty.textContent = "Click a node or edge to view properties";
-      content.appendChild(empty);
-      return;
-    }
-
-    if (selectedNode) {
-      // Node header
-      const nodeHeader = document.createElement("div");
-      nodeHeader.className = "awg-properties-header";
-      nodeHeader.innerHTML = `${ICONS.node} <span class="awg-properties-type">Node</span>`;
-      content.appendChild(nodeHeader);
-
-      // Node ID
-      const idItem = document.createElement("div");
-      idItem.className = "awg-property-item";
-      idItem.innerHTML = `<span class="awg-property-key">id</span><span class="awg-property-value">${selectedNode.id || "N/A"}</span>`;
-      content.appendChild(idItem);
-
-      // Labels
-      if (selectedNode.labels && selectedNode.labels.length > 0) {
-        const labelsItem = document.createElement("div");
-        labelsItem.className = "awg-property-item";
-        labelsItem.innerHTML = `<span class="awg-property-key">labels</span><span class="awg-property-value awg-property-labels">${selectedNode.labels.map(l => `<span class="awg-label-tag">${l}</span>`).join("")}</span>`;
-        content.appendChild(labelsItem);
-      }
-
-      // Other properties
-      Object.entries(selectedNode).forEach(([key, value]) => {
-        if (key === "id" || key === "labels" || key === "label" || key === "x" || key === "y" || key === "size" || key === "color") return;
-        const item = document.createElement("div");
-        item.className = "awg-property-item";
-        const displayValue = typeof value === "object" ? JSON.stringify(value) : String(value);
-        item.innerHTML = `<span class="awg-property-key">${key}</span><span class="awg-property-value">${displayValue}</span>`;
-        content.appendChild(item);
-      });
-    }
-
-    if (selectedEdge) {
-      // Edge header
-      const edgeHeader = document.createElement("div");
-      edgeHeader.className = "awg-properties-header";
-      edgeHeader.innerHTML = `${ICONS.edge} <span class="awg-properties-type">Relationship</span>`;
-      content.appendChild(edgeHeader);
-
-      // Edge type/label
-      if (selectedEdge.label) {
-        const typeItem = document.createElement("div");
-        typeItem.className = "awg-property-item";
-        typeItem.innerHTML = `<span class="awg-property-key">type</span><span class="awg-property-value"><span class="awg-edge-tag">${selectedEdge.label}</span></span>`;
-        content.appendChild(typeItem);
-      }
-
-      // Source/Target
-      const sourceItem = document.createElement("div");
-      sourceItem.className = "awg-property-item";
-      sourceItem.innerHTML = `<span class="awg-property-key">source</span><span class="awg-property-value awg-property-truncate">${selectedEdge.source}</span>`;
-      content.appendChild(sourceItem);
-
-      const targetItem = document.createElement("div");
-      targetItem.className = "awg-property-item";
-      targetItem.innerHTML = `<span class="awg-property-key">target</span><span class="awg-property-value awg-property-truncate">${selectedEdge.target}</span>`;
-      content.appendChild(targetItem);
-
-      // Other properties
-      Object.entries(selectedEdge).forEach(([key, value]) => {
-        if (key === "source" || key === "target" || key === "label" || key === "size" || key === "color") return;
-        const item = document.createElement("div");
-        item.className = "awg-property-item";
-        const displayValue = typeof value === "object" ? JSON.stringify(value) : String(value);
-        item.innerHTML = `<span class="awg-property-key">${key}</span><span class="awg-property-value">${displayValue}</span>`;
-        content.appendChild(item);
-      });
-    }
-  }
-
-  model.on("change:selected_node", renderProperties);
-  model.on("change:selected_edge", renderProperties);
-  renderProperties();
-
-  panel.appendChild(content);
-  return panel;
-}
-
-function togglePropertiesPanel(wrapper) {
-  const panel = wrapper.querySelector(".awg-properties-panel");
-  if (panel) {
-    panel.classList.toggle("awg-panel-open");
-  }
-}
-
-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 executeNeo4jQuery(
-      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 ===
-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 toolbar if enabled
-  if (model.get("show_toolbar")) {
-    const toolbar = createToolbar(model, wrapper);
-    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 = createSchemaSidebar(model);
-  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 (inside properties panel area)
-  if (model.get("show_settings")) {
-    const settingsPanel = createSettingsPanel(model);
-    content.appendChild(settingsPanel);
-  }
-
-  wrapper.appendChild(content);
-  el.appendChild(wrapper);
-
-  const graph = new Graph();
-
-  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",
-    });
-  });
-
-  const edges = model.get("edges") || [];
-  edges.forEach((edge, i) => {
-    graph.addEdge(edge.source, edge.target, {
-      label: edge.label || "",
-      size: edge.size || 2,
-      color: edge.color || "#94a3b8",
-    });
-  });
-
-  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",
-  });
-
-  renderer.on("clickNode", ({ node }) => {
-    const nodeData = graph.getNodeAttributes(node);
-    model.set("selected_node", { id: node, ...nodeData });
-    model.save_changes();
-  });
-
-  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();
-  });
-
-  renderer.on("clickStage", () => {
-    model.set("selected_node", null);
-    model.set("selected_edge", null);
-    model.save_changes();
-  });
-
-  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();
-  });
-
-  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();
-  });
-
-  return () => {
-    renderer.kill();
-  };
-}
-
-export default { render };
-"""
-
-_CSS = """
-/* === CSS VARIABLES === */
-.awg-wrapper {
-  --awg-bg: #ffffff;
-  --awg-bg-secondary: #f8f9fa;
-  --awg-bg-tertiary: #f3f4f6;
-  --awg-border: #e5e7eb;
-  --awg-text: #111827;
-  --awg-text-secondary: #6b7280;
-  --awg-text-muted: #9ca3af;
-  --awg-accent: #6366f1;
-  --awg-accent-hover: #4f46e5;
-  --awg-graph-bg: #fafafa;
-  --awg-input-bg: #ffffff;
-  --awg-input-border: #d1d5db;
-}
-
-.awg-wrapper.awg-dark {
-  --awg-bg: #1a1a2e;
-  --awg-bg-secondary: #16213e;
-  --awg-bg-tertiary: #0f3460;
-  --awg-border: #2d3748;
-  --awg-text: #e2e8f0;
-  --awg-text-secondary: #a0aec0;
-  --awg-text-muted: #718096;
-  --awg-accent: #818cf8;
-  --awg-accent-hover: #6366f1;
-  --awg-graph-bg: #0f0f1a;
-  --awg-input-bg: #1e1e32;
-  --awg-input-border: #3d4a5c;
-}
-
-/* === BASE === */
-.awg-wrapper {
-  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-  display: flex;
-  flex-direction: column;
-  border: 1px solid var(--awg-border);
-  border-radius: 8px;
-  overflow: hidden;
-  background: var(--awg-bg);
-  color: var(--awg-text);
-}
-
-.awg-content {
-  display: flex;
-  position: relative;
-}
-
-/* === TOOLBAR === */
-.awg-toolbar {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 8px 12px;
-  background: var(--awg-bg-secondary);
-  border-bottom: 1px solid var(--awg-border);
-  min-height: 44px;
-}
-
-.awg-query-container {
-  flex: 1;
-  display: flex;
-  align-items: center;
-  gap: 8px;
-}
-
-.awg-query-input {
-  flex: 1;
-  padding: 8px 12px;
-  border: 1px solid var(--awg-input-border);
-  border-radius: 6px;
-  font-family: "Monaco", "Menlo", "Ubuntu Mono", "Consolas", monospace;
-  font-size: 13px;
-  background: var(--awg-input-bg);
-  color: var(--awg-text);
-  transition: border-color 0.15s, box-shadow 0.15s;
-}
-
-.awg-query-input:focus {
-  outline: none;
-  border-color: var(--awg-accent);
-  box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.2);
-}
-
-.awg-query-input::placeholder {
-  color: var(--awg-text-muted);
-}
-
-/* === BUTTONS === */
-.awg-btn {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  min-width: 36px;
-  height: 36px;
-  padding: 0 10px;
-  border: 1px solid var(--awg-input-border);
-  border-radius: 6px;
-  background: var(--awg-input-bg);
-  color: var(--awg-text);
-  cursor: pointer;
-  transition: all 0.15s;
-  position: relative;
-  font-size: 13px;
-}
-
-.awg-btn:hover {
-  background: var(--awg-bg-tertiary);
-  border-color: var(--awg-text-muted);
-}
-
-.awg-btn:disabled {
-  opacity: 0.5;
-  cursor: not-allowed;
-}
-
-.awg-btn-primary {
-  background: var(--awg-accent);
-  border-color: var(--awg-accent);
-  color: #fff;
-}
-
-.awg-btn-primary:hover {
-  background: var(--awg-accent-hover);
-  border-color: var(--awg-accent-hover);
-}
-
-.awg-btn-primary:disabled {
-  background: var(--awg-text-muted);
-  border-color: var(--awg-text-muted);
-}
-
-.awg-btn-full {
-  width: 100%;
-}
-
-/* === STATUS DOTS === */
-.awg-status-dot {
-  position: absolute;
-  top: 4px;
-  right: 4px;
-  width: 8px;
-  height: 8px;
-  border-radius: 50%;
-  border: 1.5px solid var(--awg-bg);
-}
-
-.awg-status-dot-inline {
-  display: inline-block;
-  width: 8px;
-  height: 8px;
-  border-radius: 50%;
-  margin-right: 6px;
-}
-
-.awg-status-disconnected { background: #6b7280; }
-.awg-status-connecting { background: #f59e0b; animation: awg-pulse 1s infinite; }
-.awg-status-connected { background: #22c55e; }
-.awg-status-error { background: #ef4444; }
-
-@keyframes awg-pulse {
-  0%, 100% { opacity: 1; }
-  50% { opacity: 0.4; }
-}
-
-/* === SPINNER === */
-.awg-spinner {
-  width: 14px;
-  height: 14px;
-  border: 2px solid rgba(255,255,255,0.3);
-  border-top-color: #fff;
-  border-radius: 50%;
-  animation: awg-spin 0.8s linear infinite;
-}
-
-@keyframes awg-spin {
-  to { transform: rotate(360deg); }
-}
-
-/* === GRAPH CONTAINER === */
-.awg-graph-container {
-  flex: 1;
-  background: var(--awg-graph-bg);
-}
-
-/* === SETTINGS PANEL === */
-.awg-settings-panel {
-  width: 0;
-  overflow: hidden;
-  background: var(--awg-bg-secondary);
-  border-left: 1px solid var(--awg-border);
-  transition: width 0.2s ease;
-  display: flex;
-  flex-direction: column;
-}
-
-.awg-settings-panel.awg-panel-open {
-  width: 260px;
-}
-
-.awg-panel-header {
-  padding: 12px 16px;
-  font-weight: 600;
-  font-size: 13px;
-  text-transform: uppercase;
-  letter-spacing: 0.5px;
-  color: var(--awg-text-secondary);
-  border-bottom: 1px solid var(--awg-border);
-}
-
-.awg-panel-form {
-  padding: 16px;
-  display: flex;
-  flex-direction: column;
-  gap: 14px;
-  flex: 1;
-  overflow-y: auto;
-}
-
-.awg-panel-actions {
-  padding: 12px 16px;
-  border-top: 1px solid var(--awg-border);
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-}
-
-.awg-connection-status {
-  font-size: 12px;
-  color: var(--awg-text-secondary);
-  display: flex;
-  align-items: center;
-}
-
-.awg-panel-error {
-  padding: 10px 16px;
-  background: rgba(239, 68, 68, 0.1);
-  color: #ef4444;
-  font-size: 12px;
-  border-top: 1px solid rgba(239, 68, 68, 0.2);
-}
-
-/* === FORM ELEMENTS === */
-.awg-form-group {
-  display: flex;
-  flex-direction: column;
-  gap: 5px;
-}
-
-.awg-label {
-  font-size: 11px;
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 0.3px;
-  color: var(--awg-text-secondary);
-}
-
-.awg-input, .awg-select {
-  padding: 8px 10px;
-  border: 1px solid var(--awg-input-border);
-  border-radius: 5px;
-  font-size: 13px;
-  background: var(--awg-input-bg);
-  color: var(--awg-text);
-  transition: border-color 0.15s, box-shadow 0.15s;
-}
-
-.awg-input:focus, .awg-select:focus {
-  outline: none;
-  border-color: var(--awg-accent);
-  box-shadow: 0 0 0 2px rgba(99, 102, 241, 0.15);
-}
-
-.awg-select {
-  cursor: pointer;
-}
-
-.awg-select option:disabled {
-  color: var(--awg-text-muted);
-}
-
-/* === TOGGLE SWITCH === */
-.awg-toggle {
-  display: flex;
-  align-items: center;
-  cursor: pointer;
-  gap: 10px;
-}
-
-.awg-toggle input {
-  display: none;
-}
-
-.awg-toggle-slider {
-  width: 36px;
-  height: 20px;
-  background: var(--awg-input-border);
-  border-radius: 10px;
-  position: relative;
-  transition: background 0.2s;
-}
-
-.awg-toggle-slider::after {
-  content: "";
-  position: absolute;
-  top: 2px;
-  left: 2px;
-  width: 16px;
-  height: 16px;
-  background: #fff;
-  border-radius: 50%;
-  transition: transform 0.2s;
-}
-
-.awg-toggle input:checked + .awg-toggle-slider {
-  background: var(--awg-accent);
-}
-
-.awg-toggle input:checked + .awg-toggle-slider::after {
-  transform: translateX(16px);
-}
-
-.awg-toggle-label {
-  font-size: 13px;
-  color: var(--awg-text);
-}
-
-/* === SCHEMA PANEL (LEFT) === */
-.awg-schema-panel {
-  width: 0;
-  overflow: hidden;
-  background: var(--awg-bg-secondary);
-  border-right: 1px solid var(--awg-border);
-  transition: width 0.2s ease;
-  display: flex;
-  flex-direction: column;
-}
-
-.awg-schema-panel.awg-panel-open {
-  width: 220px;
-}
-
-.awg-schema-content {
-  flex: 1;
-  overflow-y: auto;
-  padding: 8px 0;
-}
-
-.awg-schema-empty {
-  padding: 20px 16px;
-  color: var(--awg-text-muted);
-  font-size: 12px;
-  text-align: center;
-}
-
-.awg-schema-section {
-  margin-bottom: 8px;
-}
-
-.awg-schema-section-header {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 8px 16px;
-  font-size: 11px;
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 0.3px;
-  color: var(--awg-text-secondary);
-}
-
-.awg-schema-item {
-  border-bottom: 1px solid var(--awg-border);
-}
-
-.awg-schema-item:last-child {
-  border-bottom: none;
-}
-
-.awg-schema-item-header {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 8px 16px;
-  cursor: pointer;
-  transition: background 0.1s;
-}
-
-.awg-schema-item-header:hover {
-  background: var(--awg-bg-tertiary);
-}
-
-.awg-schema-expand {
-  color: var(--awg-text-muted);
-  transition: transform 0.15s;
-}
-
-.awg-schema-item-expanded .awg-schema-expand {
-  transform: rotate(90deg);
-}
-
-.awg-schema-name {
-  font-size: 13px;
-  color: var(--awg-accent);
-  cursor: pointer;
-  flex: 1;
-}
-
-.awg-schema-name:hover {
-  text-decoration: underline;
-}
-
-.awg-schema-props {
-  display: none;
-  padding: 4px 16px 8px 32px;
-}
-
-.awg-schema-item-expanded .awg-schema-props {
-  display: block;
-}
-
-.awg-schema-prop {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 4px 8px;
-  font-size: 12px;
-  color: var(--awg-text-secondary);
-  cursor: pointer;
-  border-radius: 4px;
-  transition: background 0.1s;
-}
-
-.awg-schema-prop:hover {
-  background: var(--awg-bg-tertiary);
-  color: var(--awg-text);
-}
-
-.awg-schema-prop-empty {
-  color: var(--awg-text-muted);
-  font-style: italic;
-  cursor: default;
-}
-
-.awg-schema-prop-empty:hover {
-  background: transparent;
-  color: var(--awg-text-muted);
-}
-
-/* === PROPERTIES PANEL (RIGHT) === */
-.awg-properties-panel {
-  width: 0;
-  overflow: hidden;
-  background: var(--awg-bg-secondary);
-  border-left: 1px solid var(--awg-border);
-  transition: width 0.2s ease;
-  display: flex;
-  flex-direction: column;
-}
-
-.awg-properties-panel.awg-panel-open {
-  width: 260px;
-}
-
-.awg-properties-content {
-  flex: 1;
-  overflow-y: auto;
-  padding: 8px 0;
-}
-
-.awg-properties-empty {
-  padding: 20px 16px;
-  color: var(--awg-text-muted);
-  font-size: 12px;
-  text-align: center;
-}
-
-.awg-properties-header {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 10px 16px;
-  font-size: 12px;
-  font-weight: 600;
-  color: var(--awg-text-secondary);
-  border-bottom: 1px solid var(--awg-border);
-  background: var(--awg-bg-tertiary);
-}
-
-.awg-properties-type {
-  text-transform: uppercase;
-  letter-spacing: 0.3px;
-}
-
-.awg-property-item {
-  display: flex;
-  flex-direction: column;
-  padding: 8px 16px;
-  border-bottom: 1px solid var(--awg-border);
-}
-
-.awg-property-item:last-child {
-  border-bottom: none;
-}
-
-.awg-property-key {
-  font-size: 10px;
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 0.3px;
-  color: var(--awg-text-muted);
-  margin-bottom: 2px;
-}
-
-.awg-property-value {
-  font-size: 13px;
-  color: var(--awg-text);
-  word-break: break-all;
-}
-
-.awg-property-truncate {
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.awg-property-labels {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 4px;
-}
-
-.awg-label-tag {
-  display: inline-block;
-  padding: 2px 8px;
-  font-size: 11px;
-  font-weight: 500;
-  background: var(--awg-accent);
-  color: #fff;
-  border-radius: 10px;
-}
-
-.awg-edge-tag {
-  display: inline-block;
-  padding: 2px 8px;
-  font-size: 11px;
-  font-weight: 500;
-  background: var(--awg-bg-tertiary);
-  color: var(--awg-text);
-  border-radius: 4px;
-  border: 1px solid var(--awg-border);
-}
-
-/* === SMALL BUTTONS === */
-.awg-btn-sm {
-  min-width: 24px;
-  height: 24px;
-  padding: 0 4px;
-}
-
-.awg-panel-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-}
-"""
-
 
 class Graph(anywidget.AnyWidget):
-    """Interactive graph visualization widget using Sigma.js."""
+    """Interactive graph visualization widget using Sigma.js.
+
+    Supports Neo4j (browser-side) and Grafeo (Python-side) backends.
+
+    Examples
+    --------
+    Basic usage with static data:
+
+        >>> graph = Graph(
+        ...     nodes=[{"id": "a", "label": "Alice"}, {"id": "b", "label": "Bob"}],
+        ...     edges=[{"source": "a", "target": "b", "label": "KNOWS"}],
+        ... )
+
+    With Neo4j connection:
+
+        >>> graph = Graph(
+        ...     database_backend="neo4j",
+        ...     connection_uri="neo4j+s://demo.neo4jlabs.com",
+        ...     connection_username="neo4j",
+        ...     connection_password="password",
+        ... )
+
+    With Grafeo backend:
+
+        >>> import grafeo
+        >>> db = grafeo.GrafeoDB()
+        >>> graph = Graph(database_backend="grafeo", grafeo_db=db)
+    """
 
-    _esm = _ESM
-    _css = _CSS
+    _esm = get_esm()
+    _css = get_css()
 
-    # Graph data
+    # === Graph Data ===
     nodes = traitlets.List(trait=traitlets.Dict()).tag(sync=True)
     edges = traitlets.List(trait=traitlets.Dict()).tag(sync=True)
 
-    # Display settings
+    # === Display Settings ===
     width = traitlets.Int(default_value=800).tag(sync=True)
     height = traitlets.Int(default_value=600).tag(sync=True)
     background = traitlets.Unicode(default_value="#fafafa").tag(sync=True)
     show_labels = traitlets.Bool(default_value=True).tag(sync=True)
     show_edge_labels = traitlets.Bool(default_value=False).tag(sync=True)
 
-    # Selection state
+    # === Selection State ===
     selected_node = traitlets.Dict(allow_none=True, default_value=None).tag(sync=True)
     selected_edge = traitlets.Dict(allow_none=True, default_value=None).tag(sync=True)
 
-    # Toolbar visibility
+    # === Toolbar Visibility ===
     show_toolbar = traitlets.Bool(default_value=True).tag(sync=True)
     show_settings = traitlets.Bool(default_value=True).tag(sync=True)
     show_query_input = traitlets.Bool(default_value=True).tag(sync=True)
 
-    # Theme
+    # === Theme ===
     dark_mode = traitlets.Bool(default_value=True).tag(sync=True)
 
-    # Database backend
+    # === Database Backend ===
     database_backend = traitlets.Unicode(default_value="neo4j").tag(sync=True)
 
-    # Neo4j connection (browser-side)
+    # === Neo4j Connection (browser-side) ===
     connection_uri = traitlets.Unicode(default_value="").tag(sync=True)
     connection_username = traitlets.Unicode(default_value="").tag(sync=True)
     connection_password = traitlets.Unicode(default_value="").tag(sync=True)
     connection_database = traitlets.Unicode(default_value="neo4j").tag(sync=True)
 
-    # Query state
+    # === Query State ===
     query = traitlets.Unicode(default_value="").tag(sync=True)
     query_language = traitlets.Unicode(default_value="cypher").tag(sync=True)
     query_running = traitlets.Bool(default_value=False).tag(sync=True)
     query_error = traitlets.Unicode(default_value="").tag(sync=True)
 
-    # Connection state
+    # === Connection State ===
     connection_status = traitlets.Unicode(default_value="disconnected").tag(sync=True)
 
-    # Schema data
+    # === Schema Data ===
     schema_node_types = traitlets.List(trait=traitlets.Dict()).tag(sync=True)
     schema_edge_types = traitlets.List(trait=traitlets.Dict()).tag(sync=True)
 
-    # Query execution trigger (for Python backends)
+    # === Query Execution Trigger (for Python backends) ===
     _execute_query = traitlets.Int(default_value=0).tag(sync=True)
 
     def __init__(
@@ -1648,8 +117,50 @@ class Graph(anywidget.AnyWidget):
         connection_password: str = "",
         connection_database: str = "neo4j",
         grafeo_db: Any = None,
+        backend: DatabaseBackend | None = None,
         **kwargs: Any,
     ) -> None:
+        """Initialize the Graph widget.
+
+        Parameters
+        ----------
+        nodes : list[dict], optional
+            List of node dictionaries with 'id' and optional 'label', 'color', etc.
+        edges : list[dict], optional
+            List of edge dictionaries with 'source', 'target', and optional 'label'.
+        width : int
+            Widget width in pixels.
+        height : int
+            Widget height in pixels.
+        background : str
+            Background color for the graph area.
+        show_labels : bool
+            Whether to show node labels.
+        show_edge_labels : bool
+            Whether to show edge labels.
+        show_toolbar : bool
+            Whether to show the toolbar.
+        show_settings : bool
+            Whether to show the settings button.
+        show_query_input : bool
+            Whether to show the query input.
+        dark_mode : bool
+            Whether to use dark theme.
+        database_backend : str
+            Database backend: "neo4j" or "grafeo".
+        connection_uri : str
+            Neo4j connection URI.
+        connection_username : str
+            Neo4j username.
+        connection_password : str
+            Neo4j password.
+        connection_database : str
+            Neo4j database name.
+        grafeo_db : Any
+            Grafeo database instance for Python-side execution (legacy).
+        backend : DatabaseBackend | None
+            Generic database backend implementing the DatabaseBackend protocol.
+        """
         super().__init__(
             nodes=nodes or [],
             edges=edges or [],
@@ -1671,33 +182,55 @@ class Graph(anywidget.AnyWidget):
         )
         self._node_click_callbacks: list[Callable] = []
         self._edge_click_callbacks: list[Callable] = []
-        self._grafeo_db = grafeo_db
+
+        # Support both legacy grafeo_db and new generic backend
+        if backend is not None:
+            self._backend = backend
+        elif grafeo_db is not None:
+            self._backend = GrafeoBackend(grafeo_db)
+        else:
+            self._backend = None
+
+    @property
+    def backend(self) -> DatabaseBackend | None:
+        """Get the current database backend."""
+        return self._backend
+
+    @backend.setter
+    def backend(self, value: DatabaseBackend | None) -> None:
+        """Set the database backend."""
+        self._backend = value
 
     @property
     def grafeo_db(self) -> Any:
-        """Get the Grafeo database instance."""
-        return self._grafeo_db
+        """Get the Grafeo database instance (legacy property)."""
+        if isinstance(self._backend, GrafeoBackend):
+            return self._backend.db
+        return None
 
     @grafeo_db.setter
     def grafeo_db(self, value: Any) -> None:
-        """Set the Grafeo database instance."""
-        self._grafeo_db = value
+        """Set the Grafeo database instance (legacy property)."""
+        self._backend = GrafeoBackend(value) if value else None
 
     @observe("_execute_query")
     def _on_execute_query(self, change: dict) -> None:
         """Handle query execution trigger from JavaScript."""
         if change["new"] == 0:
             return  # Skip initial value
-        if self.database_backend == "grafeo" and self._grafeo_db is not None:
-            self._execute_grafeo_query()
+        if self._backend is not None:
+            self._execute_backend_query()
+
+    def _execute_backend_query(self) -> None:
+        """Execute query against the configured backend."""
+        if not self._backend:
+            self.query_error = "No database backend configured"
+            return
 
-    def _execute_grafeo_query(self) -> None:
-        """Execute query against Grafeo database."""
         try:
             self.query_running = True
             self.query_error = ""
-            result = self._grafeo_db.execute(self.query)
-            nodes, edges = self._process_grafeo_result(result)
+            nodes, edges = self._backend.execute(self.query)
             self.nodes = nodes
             self.edges = edges
         except Exception as e:
@@ -1705,68 +238,216 @@ class Graph(anywidget.AnyWidget):
         finally:
             self.query_running = False
 
-    def _process_grafeo_result(self, result: Any) -> tuple[list[dict], list[dict]]:
-        """Process Grafeo query results into nodes and edges."""
-        nodes: dict[str, dict] = {}
-        edges: list[dict] = []
-
-        # Handle result as iterable of records
-        records = list(result) if hasattr(result, "__iter__") else [result]
-
-        for record in records:
-            # Try to extract items from record
-            if hasattr(record, "items"):
-                items = record.items() if callable(record.items) else record.items
-            elif hasattr(record, "data"):
-                items = record.data().items()
-            elif isinstance(record, dict):
-                items = record.items()
-            else:
-                continue
-
-            for key, value in items:
-                if _is_node(value):
-                    node_id = _get_node_id(value)
-                    if node_id not in nodes:
-                        nodes[node_id] = _node_to_dict(value)
-                elif _is_relationship(value):
-                    edges.append(_relationship_to_dict(value))
-
-        return list(nodes.values()), edges
-
     @classmethod
     def from_dict(cls, data: dict[str, Any], **kwargs: Any) -> Graph:
-        """Create a Graph from a dictionary with nodes and edges keys."""
+        """Create a Graph from a dictionary with 'nodes' and 'edges' keys.
+
+        Parameters
+        ----------
+        data : dict
+            Dictionary with 'nodes' and 'edges' lists.
+        **kwargs
+            Additional arguments passed to Graph constructor.
+
+        Returns
+        -------
+        Graph
+            New Graph instance.
+        """
         return cls(nodes=data.get("nodes", []), edges=data.get("edges", []), **kwargs)
 
     @classmethod
     def from_cypher(cls, result: Any, **kwargs: Any) -> Graph:
-        """Create a Graph from Cypher query results."""
-        nodes: dict[str, dict] = {}
-        edges: list[dict] = []
-
-        records = list(result) if hasattr(result, "__iter__") else [result]
-
-        for record in records:
-            if hasattr(record, "items"):
-                items = record.items() if callable(record.items) else record.items
-            elif hasattr(record, "data"):
-                items = record.data().items()
-            else:
-                items = record.items() if isinstance(record, dict) else []
-
-            for key, value in items:
-                if _is_node(value):
-                    node_id = _get_node_id(value)
-                    if node_id not in nodes:
-                        nodes[node_id] = _node_to_dict(value)
-                elif _is_relationship(value):
-                    edges.append(_relationship_to_dict(value))
-
-        return cls(nodes=list(nodes.values()), edges=edges, **kwargs)
+        """Create a Graph from Cypher query results.
+
+        Parameters
+        ----------
+        result : Any
+            Query result from Neo4j driver or similar.
+        **kwargs
+            Additional arguments passed to Graph constructor.
+
+        Returns
+        -------
+        Graph
+            New Graph instance with extracted nodes and edges.
+
+        Example
+        -------
+        >>> from neo4j import GraphDatabase
+        >>> driver = GraphDatabase.driver(uri, auth=auth)
+        >>> with driver.session() as session:
+        ...     result = session.run("MATCH (n)-[r]->(m) RETURN n, r, m")
+        ...     graph = Graph.from_cypher(result)
+        """
+        from anywidget_graph.converters import CypherConverter
+
+        data = CypherConverter().convert(result)
+        return cls(nodes=data["nodes"], edges=data["edges"], **kwargs)
+
+    @classmethod
+    def from_gql(cls, result: Any, **kwargs: Any) -> Graph:
+        """Create a Graph from GQL query results.
+
+        GQL (ISO Graph Query Language) uses a similar format to Cypher.
+
+        Parameters
+        ----------
+        result : Any
+            Query result from GQL-compatible database.
+        **kwargs
+            Additional arguments passed to Graph constructor.
+
+        Returns
+        -------
+        Graph
+            New Graph instance with extracted nodes and edges.
+        """
+        from anywidget_graph.converters import GQLConverter
+
+        data = GQLConverter().convert(result)
+        return cls(nodes=data["nodes"], edges=data["edges"], **kwargs)
+
+    @classmethod
+    def from_sparql(
+        cls,
+        result: Any,
+        subject_var: str = "s",
+        predicate_var: str = "p",
+        object_var: str = "o",
+        **kwargs: Any,
+    ) -> Graph:
+        """Create a Graph from SPARQL query results.
+
+        Parameters
+        ----------
+        result : Any
+            SPARQL query result (e.g., from RDFLib or SPARQLWrapper).
+        subject_var : str
+            Variable name for subjects (default: "s").
+        predicate_var : str
+            Variable name for predicates (default: "p").
+        object_var : str
+            Variable name for objects (default: "o").
+        **kwargs
+            Additional arguments passed to Graph constructor.
+
+        Returns
+        -------
+        Graph
+            New Graph instance with extracted nodes and edges.
+
+        Example
+        -------
+        >>> from rdflib import Graph as RDFGraph
+        >>> g = RDFGraph()
+        >>> g.parse("data.ttl")
+        >>> result = g.query("SELECT ?s ?p ?o WHERE { ?s ?p ?o }")
+        >>> graph = Graph.from_sparql(result)
+        """
+        from anywidget_graph.converters import SPARQLConverter
+
+        converter = SPARQLConverter(
+            subject_var=subject_var,
+            predicate_var=predicate_var,
+            object_var=object_var,
+        )
+        data = converter.convert(result)
+        return cls(nodes=data["nodes"], edges=data["edges"], **kwargs)
+
+    @classmethod
+    def from_gremlin(cls, result: Any, **kwargs: Any) -> Graph:
+        """Create a Graph from Gremlin/TinkerPop query results.
+
+        Parameters
+        ----------
+        result : Any
+            Gremlin traversal result.
+        **kwargs
+            Additional arguments passed to Graph constructor.
+
+        Returns
+        -------
+        Graph
+            New Graph instance with extracted nodes and edges.
+
+        Example
+        -------
+        >>> from gremlin_python.driver import client
+        >>> gremlin_client = client.Client('ws://localhost:8182/gremlin', 'g')
+        >>> result = gremlin_client.submit("g.V().limit(10)").all().result()
+        >>> graph = Graph.from_gremlin(result)
+        """
+        from anywidget_graph.converters import GremlinConverter
+
+        data = GremlinConverter().convert(result)
+        return cls(nodes=data["nodes"], edges=data["edges"], **kwargs)
+
+    @classmethod
+    def from_graphql(
+        cls,
+        result: Any,
+        nodes_path: str | None = None,
+        edges_path: str | None = None,
+        id_field: str = "id",
+        label_field: str = "name",
+        **kwargs: Any,
+    ) -> Graph:
+        """Create a Graph from GraphQL JSON response.
+
+        Parameters
+        ----------
+        result : Any
+            GraphQL JSON response.
+        nodes_path : str | None
+            Dot-separated path to nodes list (e.g., "data.users").
+        edges_path : str | None
+            Dot-separated path to edges list.
+        id_field : str
+            Field name for node IDs (default: "id").
+        label_field : str
+            Field name for node labels (default: "name").
+        **kwargs
+            Additional arguments passed to Graph constructor.
+
+        Returns
+        -------
+        Graph
+            New Graph instance with extracted nodes and edges.
+
+        Example
+        -------
+        >>> import requests
+        >>> response = requests.post(url, json={"query": query})
+        >>> graph = Graph.from_graphql(
+        ...     response.json(),
+        ...     nodes_path="data.characters.results",
+        ... )
+        """
+        from anywidget_graph.converters import GraphQLConverter
+
+        converter = GraphQLConverter(
+            nodes_path=nodes_path,
+            edges_path=edges_path,
+            id_field=id_field,
+            label_field=label_field,
+        )
+        data = converter.convert(result)
+        return cls(nodes=data["nodes"], edges=data["edges"], **kwargs)
 
     def on_node_click(self, callback: Callable[[str, dict], None]) -> Callable:
-        """Register a callback for node click events."""
+        """Register a callback for node click events.
+
+        Parameters
+        ----------
+        callback : Callable[[str, dict], None]
+            Function called with (node_id, node_attributes) when a node is clicked.
+
+        Returns
+        -------
+        Callable
+            The callback function (for decorator usage).
+        """
         self._node_click_callbacks.append(callback)
 
         def observer(change: dict) -> None:
@@ -1780,7 +461,18 @@ class Graph(anywidget.AnyWidget):
         return callback
 
     def on_edge_click(self, callback: Callable[[dict], None]) -> Callable:
-        """Register a callback for edge click events."""
+        """Register a callback for edge click events.
+
+        Parameters
+        ----------
+        callback : Callable[[dict], None]
+            Function called with edge data when an edge is clicked.
+
+        Returns
+        -------
+        Callable
+            The callback function (for decorator usage).
+        """
         self._edge_click_callbacks.append(callback)
 
         def observer(change: dict) -> None:
@@ -1790,85 +482,3 @@ class Graph(anywidget.AnyWidget):
 
         self.observe(observer, names=["selected_edge"])
         return callback
-
-
-def _is_node(obj: Any) -> bool:
-    if hasattr(obj, "labels") and hasattr(obj, "element_id"):
-        return True
-    if hasattr(obj, "labels") and hasattr(obj, "properties"):
-        return True
-    if isinstance(obj, dict) and "id" in obj:
-        return True
-    return False
-
-
-def _is_relationship(obj: Any) -> bool:
-    if hasattr(obj, "type") and hasattr(obj, "start_node"):
-        return True
-    if hasattr(obj, "type") and hasattr(obj, "source") and hasattr(obj, "target"):
-        return True
-    if isinstance(obj, dict) and "source" in obj and "target" in obj:
-        return True
-    return False
-
-
-def _get_node_id(node: Any) -> str:
-    if hasattr(node, "element_id"):
-        return str(node.element_id)
-    if hasattr(node, "id"):
-        return str(node.id)
-    if isinstance(node, dict):
-        return str(node.get("id", id(node)))
-    return str(id(node))
-
-
-def _node_to_dict(node: Any) -> dict:
-    result: dict[str, Any] = {"id": _get_node_id(node)}
-
-    if hasattr(node, "labels"):
-        labels = list(node.labels) if hasattr(node.labels, "__iter__") else [node.labels]
-        if labels:
-            result["label"] = labels[0]
-            result["labels"] = labels
-
-    if hasattr(node, "properties"):
-        props = node.properties if isinstance(node.properties, dict) else dict(node.properties)
-        result.update(props)
-    elif hasattr(node, "items"):
-        result.update(dict(node))
-    elif isinstance(node, dict):
-        result.update(node)
-
-    if "label" not in result and "name" in result:
-        result["label"] = result["name"]
-
-    return result
-
-
-def _relationship_to_dict(rel: Any) -> dict:
-    result: dict[str, Any] = {}
-
-    if hasattr(rel, "start_node") and hasattr(rel, "end_node"):
-        result["source"] = _get_node_id(rel.start_node)
-        result["target"] = _get_node_id(rel.end_node)
-    elif hasattr(rel, "source") and hasattr(rel, "target"):
-        result["source"] = _get_node_id(rel.source)
-        result["target"] = _get_node_id(rel.target)
-    elif isinstance(rel, dict):
-        result["source"] = str(rel.get("source", ""))
-        result["target"] = str(rel.get("target", ""))
-
-    if hasattr(rel, "type"):
-        result["label"] = str(rel.type)
-    elif isinstance(rel, dict) and "type" in rel:
-        result["label"] = str(rel["type"])
-    elif isinstance(rel, dict) and "label" in rel:
-        result["label"] = str(rel["label"])
-
-    if hasattr(rel, "properties"):
-        props = rel.properties if isinstance(rel.properties, dict) else dict(rel.properties)
-        result.update(props)
-    elif hasattr(rel, "items") and not isinstance(rel, dict):
-        result.update(dict(rel))
-
-    return result