topologicpy 0.8.57__py3-none-any.whl → 0.8.58__py3-none-any.whl

topologicpy/Kuzu.py

@@ -2,14 +2,6 @@ from __future__ import annotations
 import threading, contextlib, time, json
 from typing import Dict, Any, List, Optional
 
-
-# Optional TopologicPy imports (make this file safe to import without TopologicPy)
-from topologicpy.Graph import Graph
-from topologicpy.Vertex import Vertex
-from topologicpy.Edge import Edge
-from topologicpy.Dictionary import Dictionary
-from topologicpy.Topology import Topology
-
 import os
 import warnings
 
@@ -123,7 +115,7 @@ class _Mgr:
     def ensure_schema(self):
         # Node tables
         self.exec("""
-        CREATE NODE TABLE IF NOT EXISTS GraphCard(
+        CREATE NODE TABLE IF NOT EXISTS Graph(
             id STRING,
             label STRING,
             num_nodes INT64,
@@ -147,7 +139,7 @@ class _Mgr:
         
         # Relationship tables
         self.exec("""
-        CREATE REL TABLE IF NOT EXISTS CONNECT(FROM Vertex TO Vertex, label STRING, props STRING);
+        CREATE REL TABLE IF NOT EXISTS Edge(FROM Vertex TO Vertex, label STRING, props STRING);
         """, write=True)
 
         # Figure out later if we need sessions and steps
@@ -178,31 +170,18 @@ class _Mgr:
 
 
 class Kuzu:
-    """
-    TopologicPy-style class of static methods for Kùzu integration.
-
-    Notes
-    -----
-    - All methods are *static* to match TopologicPy's style.
-    - Graph persistence:
-        * Vertices: stored in `Vertex` with (id, graph_id, label, props JSON)
-        * Edges: stored as `CONNECT` relations a->b with label + props JSON
-        * We assume undirected design intent; only one CONNECT is stored (a->b),
-          but TopologicPy Graph treats edges as undirected by default.
-    """
-
     # ---------- Core (DB + Connection + Schema) ----------
     @staticmethod
-    def EnsureSchema(db_path: str, silent: bool = False) -> bool:
+    def EnsureSchema(manager, silent: bool = False) -> bool:
         """
-        Ensures the required Kùzu schema exists in the database at `db_path`.
+        Ensures the required Kùzu schema exists in the database at `path`.
 
         Parameters
         ----------
-        db_path : str
-            Path to the Kùzu database directory. It will be created if it does not exist.
+        manager : Kuzu.Manager
+            Path to the Kùzu database. It will be created if it does not exist.
         silent : bool , optional
-            If True, suppresses error messages. Default is False.
+            If set to True, error and warning messages are suppressed. Default is False.
 
         Returns
         -------
@@ -210,63 +189,120 @@ class Kuzu:
             True if successful, False otherwise.
         """
         try:
-            mgr = _Mgr(db_path)
-            mgr.ensure_schema()
+            manager.ensure_schema()
             return True
         except Exception as e:
             if not silent:
-                print(f"Kuzu.EnsureSchema - Error: {e}")
+                print(f"Kuzu.EnsureSchema - Error: {e}. Returning False.")
             return False
 
     @staticmethod
-    def Database(db_path: str):
+    def Database(path: str, silent: bool = False):
         """
-        Returns the underlying `kuzu.Database` instance for `db_path`.
+        Returns the underlying `kuzu.Database` instance for `path`.
+
+        Parameters
+        ----------
+        path : str
+            Path to the Kùzu database. It will be created if it does not exist.
+        silent : bool , optional
+            If set to True, error and warning messages are suppressed. Default is False.
+
+        Returns
+        -------
+        kuzu.Database
+            The Kuzu database found at the path.
         """
-        return _db_cache.get(db_path)
+        try:
+            return _db_cache.get(path)
+        except Exception as e:
+            if not silent:
+                print(f"Kuzu.Database - Error: {e}. Returning None.")
+            return None
 
     @staticmethod
-    def Connection(db_path: str):
+    def Connection(manager, silent: bool = False):
+        """
+        Returns a `kuzu.Connection` bound to the database at `path`.
+
+        Parameters
+        ----------
+        manager : Kuzu.Manager
+            The Manager to the Kùzu database.
+        silent : bool , optional
+            If set to True, error and warning messages are suppressed. Default is False.
+
+        Returns
+        -------
+        kuzu.Connection
+            The Kuzu live connection. Do NOT use across threads.
         """
-        Returns a `kuzu.Connection` bound to the database at `db_path`.
+        try:
+            with manager.read() as c:
+                return c  # Note: returns a live connection (do not use across threads)
+        except Exception as e:
+            if not silent:
+                print(f"Kuzu.Connection - Error: {e}. Returning None.")
+            return None        
+    
+    @staticmethod
+    def Manager(path: str, silent: bool = False):
         """
-        mgr = _Mgr(db_path)
-        with mgr.read() as c:
-            return c  # Note: returns a live connection (do not use across threads)
+        Returns a lightweight manager bound to the database at `path`.
+        Parameters
+        ----------
+        path : str
+            Path to the Kùzu database. It will be created if it does not exist.
+        silent : bool , optional
+            If set to True, error and warning messages are suppressed. Default is False.
 
-    # ---------- Graph <-> DB Conversion ----------
+        Returns
+        -------
+        Kuzu.Manager
+            The Kuzu Manager.
+        """
+        try:
+            return _Mgr(path)
+        except Exception as e:
+            if not silent:
+                print(f"Kuzu.Manager - Error: {e}. Returning None.")
+            return None 
 
     @staticmethod
-    def UpsertGraph(db_path: str,
+    def UpsertGraph(manager,
                     graph,
-                    graphIDKey: Optional[str] = None,
-                    vertexIDKey: Optional[str] = None,
-                    vertexLabelKey: Optional[str] = None,
+                    graphIDKey: str = None,
+                    vertexIDKey: str = None,
+                    vertexLabelKey: str = None,
                     mantissa: int = 6,
                     silent: bool = False) -> str:
         """
-        Upserts (deletes prior + inserts new) a TopologicPy graph and its GraphCard.
+        Upserts (deletes prior + inserts new) a TopologicPy graph.
 
         Parameters
         ----------
-        db_path : str
-            Kùzu database path.
+        manager : Kuzu.Manager
+            The Kuzu database manager.
         graph : topologicpy.Graph
             The input TopologicPy graph.
         graphIDKey : str , optional
-            The graph dictionary key under which the graph ID is stored. If None, a UUID is generated.
-        title, domain, geo, time_start, time_end, summary : str , optional
-            Optional metadata for GraphCard.
+            The graph dictionary key under which the graph ID is stored. If None, a UUID is generated and stored under 'id'.
+        vertexIDKey : str , optional
+            The vertex dictionary key under which the vertex ID is stored. If None, a UUID is generated and stored under 'id'.
+        edgeIDKey : str , optional
+            The edge dictionary key under which the edge ID is stored. If None, a UUID is generated and stored under 'id'.
         silent : bool , optional
-            If True, suppresses error messages. Default is False.
+            If set to True, error and warning messages are suppressed. Default is False.
 
         Returns
         -------
         str
             The graph_id used.
         """
+        from topologicpy.Graph import Graph
         from topologicpy.Topology import Topology
         from topologicpy.Dictionary import Dictionary
+
         d = Topology.Dictionary(graph)
         if graphIDKey is None:
             gid =  Topology.UUID(graph)
@@ -280,22 +316,21 @@ class Kuzu:
         e_props = mesh_data['edgeDictionaries']
         num_nodes = len(verts)
         num_edges = len(edges)
-        mgr = _Mgr(db_path)
         try:
-            mgr.ensure_schema()
-            # Upsert GraphCard
-            mgr.exec("MATCH (g:GraphCard) WHERE g.id = $id DELETE g;", {"id": gid}, write=True)
-            mgr.exec("""
-                CREATE (g:GraphCard {id:$id, num_nodes:$num_nodes, num_edges: $num_edges, props:$props});
+            manager.ensure_schema()
+            # Upsert Graph
+            manager.exec("MATCH (g:Graph) WHERE g.id = $id DELETE g;", {"id": gid}, write=True)
+            manager.exec("""
+                CREATE (g:Graph {id:$id, num_nodes:$num_nodes, num_edges: $num_edges, props:$props});
             """, {"id": gid, "num_nodes": num_nodes, "num_edges": num_edges, "props": json.dumps(g_props)}, write=True)
 
             # Remove existing vertices/edges for this graph_id
-            mgr.exec("""
-                MATCH (a:Vertex)-[r:CONNECT]->(b:Vertex)
+            manager.exec("""
+                MATCH (a:Vertex)-[r:Edge]->(b:Vertex)
                 WHERE a.graph_id = $gid AND b.graph_id = $gid
                 DELETE r;
             """, {"gid": gid}, write=True)
-            mgr.exec("MATCH (v:Vertex) WHERE v.graph_id = $gid DELETE v;", {"gid": gid}, write=True)
+            manager.exec("MATCH (v:Vertex) WHERE v.graph_id = $gid DELETE v;", {"gid": gid}, write=True)
 
             # Insert vertices
             for i, v in enumerate(verts):
@@ -308,7 +343,7 @@ class Kuzu:
                     label = str(i)
                 else:
                     label = v_props[i].get(vertexIDKey, str(i))
-                mgr.exec("""
+                manager.exec("""
                     CREATE (v:Vertex {id:$id, graph_id:$gid, label:$label, props:$props, x:$x, y:$y, z:$z});
                 """, {"id": vid, "gid": gid, "label": label, "x": x, "y": y, "z": z,
                         "props": json.dumps(v_props[i])}, write=True)
@@ -317,9 +352,9 @@ class Kuzu:
             for i, e in enumerate(edges):
                 a_id = v_props[e[0]].get(vertexIDKey, f"{gid}:{e[0]}")
                 b_id = v_props[e[1]].get(vertexIDKey, f"{gid}:{e[1]}")
-                mgr.exec("""
+                manager.exec("""
                     MATCH (a:Vertex {id:$a}), (b:Vertex {id:$b})
-                    CREATE (a)-[:CONNECT {label:$label, props:$props}]->(b);
+                    CREATE (a)-[:Edge {label:$label, props:$props}]->(b);
                 """, {"a": a_id, "b": b_id,
                         "label": e_props[i].get("label", str(i)),
                         "props": json.dumps(e_props[i])}, write=True)
@@ -327,29 +362,40 @@ class Kuzu:
             return gid
         except Exception as e:
             if not silent:
-                print(f"Kuzu.UpsertGraph - Error: {e}")
-            raise
+                print(f"Kuzu.UpsertGraph - Error: {e}. Returning None.")
+            return None
 
     @staticmethod
-    def GraphByID(db_path: str, graphID: str, silent: bool = False):
+    def GraphByID(manager, graphID: str, silent: bool = False):
         """
-        Reads a graph with id `graph_id` from Kùzu and constructs a TopologicPy graph.
+        Constructs a TopologicPy graph from from Kùzu using the graphID input parameter.
+
+        Parameters
+        ----------
+        manager : Kuzu.Manager
+            The manager of the Kùzu database.
+        graphID : str , optional
+            The graph ID to retrieve from Kùzu.
+        silent : bool , optional
+            If set to True, error and warning messages are suppressed. Default is False.
 
         Returns
         -------
         topologicpy.Graph
             A new TopologicPy Graph, or None on error.
         """
-        # if TGraph is None:
-        #     raise _KuzuError("TopologicPy is required to use Kuzu.ReadTopologicGraph.")
         import random
-        mgr = _Mgr(db_path)
+        from topologicpy.Graph import Graph
+        from topologicpy.Dictionary import Dictionary
+        from topologicpy.Vertex import Vertex
+        from topologicpy.Edge import Edge
+        from topologicpy.Topology import Topology
 
         try:
-            mgr.ensure_schema()
-            # Read the GraphCard
-            g = mgr.exec("""
-                    MATCH (g:GraphCard) WHERE g.id = $id
+            manager.ensure_schema()
+            # Read the Graph
+            g = manager.exec("""
+                    MATCH (g:Graph) WHERE g.id = $id
                     RETURN g.id AS id, g.num_nodes AS num_nodes, g.num_edges AS num_edges, g.props AS props
                     ;
                      """, {"id": graphID}, write=False) or None
@@ -359,7 +405,7 @@ class Kuzu:
             g_dict = dict(json.loads(g.get("props") or "{}") or {})
             g_dict = Dictionary.ByPythonDictionary(g_dict)
             # Read vertices
-            rows_v = mgr.exec("""
+            rows_v = manager.exec("""
                 MATCH (v:Vertex) WHERE v.graph_id = $gid
                 RETURN v.id AS id, v.label AS label, v.x AS x, v.y AS y, v.z AS z, v.props AS props
                 ORDER BY id;
@@ -369,9 +415,9 @@ class Kuzu:
             vertices = []
             for row in rows_v:
                 try:
-                    x = row.get("x") or random.uniform(0,1000)
-                    y = row.get("y") or random.uniform(0,1000)
-                    z = row.get("z") or random.uniform(0,1000)
+                    x = row.get("x", random.uniform(0,1000))
+                    y = row.get("y", random.uniform(0,1000))
+                    z = row.get("z", random.uniform(0,1000))
                 except:
                     x = random.uniform(0,1000)
                     y = random.uniform(0,1000)
@@ -392,8 +438,8 @@ class Kuzu:
                 vertices.append(v)
 
             # Read edges
-            rows_e = mgr.exec("""
-                MATCH (a:Vertex)-[r:CONNECT]->(b:Vertex)
+            rows_e = manager.exec("""
+                MATCH (a:Vertex)-[r:Edge]->(b:Vertex)
                 WHERE a.graph_id = $gid AND b.graph_id = $gid
                 RETURN a.id AS a_id, b.id AS b_id, r.label AS label, r.props AS props;
             """, {"gid": graphID}, write=False) or []
@@ -423,61 +469,50 @@ class Kuzu:
             return g
         except Exception as e:
             if not silent:
-                print(f"Kuzu.GraphByID - Error: {e}")
+                print(f"Kuzu.GraphByID - Error: {e}. Returning None.")
             return None
 
     @staticmethod
     def GraphsByQuery(
-        db_path: str,
+        manager,
         query: str,
         params: dict | None = None,
-        graphIDKey: str = "graph_id",
         silent: bool = False,
     ):
         """
         Executes a Kùzu Cypher query and returns a list of TopologicPy Graphs.
-        The query should return at least one column identifying each graph.
-        By default this column is expected to be named 'graph_id', but you can
-        override that via `graph_id_field`.
 
         The method will:
         1) run the query,
-        2) extract distinct graph IDs from the result set (using `graph_id_field`
-            if present; otherwise it attempts to infer IDs from common fields like
-            'a_id', 'b_id', or 'id' that look like '<graph_id>:<vertex_index>'),
-        3) reconstruct each graph via Kuzu.ReadTopologicGraph(...).
+        2) extract distinct graph IDs from the result set.
+        3) reconstruct each graph via Kuzu.GraphByID(...).
 
         Parameters
         ----------
-        db_path : str
-            Path to the Kùzu database directory.
+        manager : Kuzu.Manager
+            The manager of the Kùzu database.
         query : str
             A valid Kùzu Cypher query.
         params : dict , optional
             Parameters to pass with the query.
-        graph_id_field : str , optional
-            The field name in the query result that contains the graph ID(s).
-            Default is "graph_id".
         silent : bool , optional
-            If True, suppresses errors and returns an empty list on failure.
+            If set to True, error and warning messages are suppressed. Default is False.
 
         Returns
         -------
-        list[topologicpy.Graph]
+        list[topologic_core.Graph]
             A list of reconstructed TopologicPy graphs.
+        
         """
-        # if TGraph is None:
-        #     raise _KuzuError("TopologicPy is required to use Kuzu.GraphsFromQuery.")
 
         try:
-            mgr = _Mgr(db_path)
-            mgr.ensure_schema()
-            rows = mgr.exec(query, params or {}, write=False) or []
+            manager.ensure_schema()
+            rows = manager.exec(query, params or {}, write=False) or []
 
             # Collect distinct graph IDs
             gids = []
             for r in rows:
-                gid = r.get(graphIDKey)
+                gid = r.get('graph_id')
 
                 # Fallback: try to infer from common id fields like "<graph_id>:<i>"
                 if gid is None:
@@ -493,42 +528,55 @@ class Kuzu:
             # Reconstruct each graph
             graphs = []
             for gid in gids:
-                g = Kuzu.GraphByID(db_path, gid, silent=True)
+                g = Kuzu.GraphByID(path, gid, silent=silent)
                 if g is not None:
                     graphs.append(g)
             return graphs
 
         except Exception as e:
             if not silent:
-                print(f"Kuzu.GraphsByQuery - Error: {e}")
-            return []
+                print(f"Kuzu.GraphsByQuery - Error: {e}. Returning None.")
+            return None
 
     @staticmethod
-    def DeleteGraph(db_path: str, graph_id: str, silent: bool = False) -> bool:
+    def DeleteGraph(manager, graphID: str, silent: bool = False) -> bool:
         """
-        Deletes a graph (vertices/edges) and its GraphCard by id.
+        Deletes a graph (vertices, edges, and graphCard) by id.
+
+        Parameters
+        ----------
+        manager : Kuzu.Manager
+            The manager of the Kùzu database.
+        graphID : str
+            The id of the graph to be deleted.
+        silent : bool , optional
+            If set to True, error and warning messages are suppressed. Default is False.
+        
+        Returns
+        -------
+        bool
+            True on success, False otherwise.
         """
         try:
-            mgr = _Mgr(db_path)
-            mgr.ensure_schema()
+            manager.ensure_schema()
             # Delete edges
-            mgr.exec("""
-                MATCH (a:Vertex)-[r:CONNECT]->(b:Vertex)
+            manager.exec("""
+                MATCH (a:Vertex)-[r:Edge]->(b:Vertex)
                 WHERE a.graph_id = $gid AND b.graph_id = $gid
                 DELETE r;
-            """, {"gid": graph_id}, write=True)
+            """, {"gid": graphID}, write=True)
             # Delete vertices
-            mgr.exec("MATCH (v:Vertex) WHERE v.graph_id = $gid DELETE v;", {"gid": graph_id}, write=True)
+            manager.exec("MATCH (v:Vertex) WHERE v.graph_id = $gid DELETE v;", {"gid": graphID}, write=True)
             # Delete card
-            mgr.exec("MATCH (g:GraphCard) WHERE g.id = $gid DELETE g;", {"gid": graph_id}, write=True)
+            manager.exec("MATCH (g:Graph) WHERE g.id = $gid DELETE g;", {"gid": graphID}, write=True)
             return True
         except Exception as e:
             if not silent:
-                print(f"Kuzu.DeleteGraph - Error: {e}")
+                print(f"Kuzu.DeleteGraph - Error: {e}. Returning False.")
             return False
     
     @staticmethod
-    def EmptyDatabase(db_path: str, drop_schema: bool = False, recreate_schema: bool = True, silent: bool = False) -> bool:
+    def EmptyDatabase(manager, dropSchema: bool = False, recreateSchema: bool = True, silent: bool = False) -> bool:
         """
         Empties the Kùzu database at `db_path`.
 
@@ -538,14 +586,14 @@ class Kuzu:
 
         Parameters
         ----------
-        db_path : str
-            Path to the Kùzu database directory.
-        drop_schema : bool , optional
+        manager : Kuzu Manager
+            The manager of the Kùzu database.
+        dropSchema : bool , optional
             If True, DROP the known tables instead of deleting rows. Default False.
-        recreate_schema : bool , optional
+        recreateSchema : bool , optional
             If True and drop_schema=True, re-create the minimal schema after dropping. Default True.
         silent : bool , optional
-            Suppress errors if True. Default False.
+            If set to True, error and warning messages are suppressed. Default is False.
 
         Returns
         -------
@@ -553,37 +601,350 @@ class Kuzu:
             True on success, False otherwise.
         """
         try:
-            mgr = _Mgr(db_path)
-            # Ensure DB exists (does not create tables unless needed)
-            mgr.ensure_schema()
+            manager.ensure_schema()
 
-            if drop_schema:
+            if dropSchema:
                 # Drop relationship tables FIRST (to release dependencies), then node tables.
                 # IF EXISTS is convenient; if your Kùzu version doesn't support it, remove and ignore exceptions.
                 for stmt in [
-                    "DROP TABLE IF EXISTS CONNECT;",
+                    "DROP TABLE IF EXISTS Edge;",
                     "DROP TABLE IF EXISTS Vertex;",
-                    "DROP TABLE IF EXISTS GraphCard;",
+                    "DROP TABLE IF EXISTS Graph;",
                 ]:
                     try:
-                        mgr.exec(stmt, write=True)
+                        manager.exec(stmt, write=True)
                     except Exception as _e:
                         if not silent:
                             print(f"Kuzu.EmptyDatabase - Warning dropping table: {_e}")
 
-                if recreate_schema:
-                    mgr.ensure_schema()
+                if recreateSchema:
+                    manager.ensure_schema()
                 return True
 
             # Soft clear: remove all relationships, then all nodes (covers all labels/tables).
             # Delete all edges (any direction)
-            mgr.exec("MATCH (a)-[r]->(b) DELETE r;", write=True)
+            manager.exec("MATCH (a)-[r]->(b) DELETE r;", write=True)
             # Delete all nodes (from all node tables)
-            mgr.exec("MATCH (n) DELETE n;", write=True)
+            manager.exec("MATCH (n) DELETE n;", write=True)
             return True
 
         except Exception as e:
             if not silent:
-                print(f"Kuzu.EmptyDatabase - Error: {e}")
+                print(f"Kuzu.EmptyDatabase - Error: {e}. Returning False.")
             return False
 
+    @staticmethod
+    def ListGraphs(manager, where: dict = None, limit: int = 100, offset: int = 0, silent: bool = False) -> list[dict]:
+        """
+        Lists Graph metadata with simple filtering and pagination.
+
+        Parameters
+        ----------
+        manager : Kuzu.Manager
+            The manager of the Kùzu database.
+        where : dict , optional
+            The filter python dictionaries. Supported filters in `where` (all optional):
+            - id (exact match)
+            - label (substring match)
+            - props_contains (substring match against JSON/text in `props`)
+            - props_equals (exact string match against `props`)
+            - min_nodes / max_nodes (integers)
+            - min_edges / max_edges (integers)
+        limit : int , optional
+            The desired limit of returned Graphs. Default is 100.
+        offset : int , optional
+            The desired offset of the returned Graphs (skips the first number of Graphs specified by the offset and returns the remaining cards up to the specified limit). The offset is useful if pagination is needed. Default is 0.
+        silent : bool , optional
+            If set to True, error and warning messages are suppressed. Default is False.
+
+        Returns
+        -------
+        list
+            The list of found Graph python dictionaries.
+
+        """
+
+        manager.ensure_schema()
+        where = where or {}
+
+        conds: list[str] = []
+        params: dict = {}
+
+        if "id" in where and where["id"]:
+            conds.append("g.id = $id")
+            params["id"] = str(where["id"])
+
+        if "label" in where and where["label"]:
+            # Cypher-style infix CONTAINS
+            conds.append("g.label CONTAINS $label_sub")
+            params["label_sub"] = str(where["label"])
+
+        if "props_contains" in where and where["props_contains"]:
+            conds.append("g.props CONTAINS $props_sub")
+            params["props_sub"] = str(where["props_contains"])
+
+        if "props_equals" in where and where["props_equals"]:
+            conds.append("g.props = $props_equals")
+            params["props_equals"] = str(where["props_equals"])
+
+        if "min_nodes" in where and where["min_nodes"] is not None:
+            conds.append("g.num_nodes >= $min_nodes")
+            params["min_nodes"] = int(where["min_nodes"])
+
+        if "max_nodes" in where and where["max_nodes"] is not None:
+            conds.append("g.num_nodes <= $max_nodes")
+            params["max_nodes"] = int(where["max_nodes"])
+
+        if "min_edges" in where and where["min_edges"] is not None:
+            conds.append("g.num_edges >= $min_edges")
+            params["min_edges"] = int(where["min_edges"])
+
+        if "max_edges" in where and where["max_edges"] is not None:
+            conds.append("g.num_edges <= $max_edges")
+            params["max_edges"] = int(where["max_edges"])
+
+        where_clause = ("WHERE " + " AND ".join(conds)) if conds else ""
+        q = f"""
+            MATCH (g:Graph)
+            {where_clause}
+            RETURN g.id AS id, g.label AS label,
+                g.num_nodes AS num_nodes, g.num_edges AS num_edges,
+                g.props AS props
+            ORDER BY id
+            SKIP $__offset LIMIT $__limit;
+        """
+ 
+        params["__offset"] = max(0, int(offset or 0))
+        params["__limit"] = max(0, int(limit or 100))
+
+        return manager.exec(q, params, write=False) or []
+    
+
+    @staticmethod
+    def ByCSVPath(
+        manager,
+        path: str,
+        graphIDPrefix: str = "g",
+        graphIDHeader="graph_id",
+        graphLabelHeader="label",
+        edgeSRCHeader="src_id",
+        edgeDSTHeader="dst_id",
+        edgeLabelHeader="label",
+        nodeIDHeader="node_id",
+        nodeLabelHeader="label",
+        nodeXHeader="X",
+        nodeYHeader="Y",
+        nodeZHeader="Z",
+        silent: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Load node/edge/graph CSVs from a folder (using its .yaml meta) and upsert them
+        directly into Kùzu using the schema defined in Kuzu.py:
+
+        - NODE TABLE Graph(id STRING PRIMARY KEY, label STRING, num_nodes INT64, num_edges INT64, props STRING)
+        - NODE TABLE Vertex(id STRING PRIMARY KEY, graph_id STRING, label STRING, x DOUBLE, y DOUBLE, z DOUBLE, props STRING)
+        - REL  TABLE Edge(FROM Vertex TO Vertex, label STRING, props STRING)
+
+        Parameters
+        ----------
+        manager : Kuzu.Manager
+            An initialized Kùzu manager; must provide ensure_schema() and exec(query, params, write=True/False).
+        path : str
+            Folder containing a dataset YAML (e.g., meta.yaml) that points to nodes/edges/graphs CSVs.
+        graphIDPrefix : str
+            Prefix for materialized graph IDs (default "g"); e.g., graph 0 -> "g0".
+        graphIDHeader : str , optional
+            The column header string used to specify the graph id. Default is "graph_id".
+        graphLabelHeader : str , optional
+            The column header string used to specify the graph label. Default is "label".
+        edgeSRCHeader : str , optional
+            The column header string used to specify the source vertex id of edges. Default is "src_id".
+        edgeDSTHeader : str , optional
+            The column header string used to specify the destination vertex id of edges. Default is "dst_id".
+        edgeLabelHeader : str , optional
+            The column header string used to specify the label of edges. Default is "label".
+        nodeIDHeader : str , optional
+            The column header string used to specify the id of nodes. Default is "node_id".
+        nodeLabelHeader : str , optional
+            The column header string used to specify the label of nodes. Default is "label".
+        nodeXHeader : str , optional
+            The column header string used to specify the X coordinate of nodes. Default is "X".
+        nodeYHeader : str , optional
+            The column header string used to specify the Y coordinate of nodes. Default is "Y".
+        nodeZHeader : str , optional
+            The column header string used to specify the Z coordinate of nodes. Default is "Z".
+        silent : bool
+            If True, suppress warnings.
+
+        Returns
+        -------
+        dict
+            {"graphs_upserted": int, "graph_ids": [str, ...]}
+        """
+        import os
+        import glob
+        import json
+        import numbers
+        import pandas as pd
+        import yaml
+        import random
+
+        # ---------- Helpers (mirroring your CSV loader’s patterns) ----------
+        def _find_yaml_files(folder_path: str):
+            return glob.glob(os.path.join(folder_path, "*.yaml"))
+
+        def _read_yaml(file_path: str):
+            with open(file_path, "r", encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+            edge_data = data.get("edge_data", [])
+            node_data = data.get("node_data", [])
+            graph_data = data.get("graph_data", {})
+            edges_rel = edge_data[0].get("file_name") if edge_data else None
+            nodes_rel = node_data[0].get("file_name") if node_data else None
+            graphs_rel = graph_data.get("file_name")
+            return graphs_rel, edges_rel, nodes_rel
+
+        def _props_from_row(row: pd.Series, exclude: set) -> str:
+            d = {}
+            for k, v in row.items():
+                if k in exclude:
+                    continue
+                # normalize NaN -> None for clean JSON
+                if isinstance(v, float) and pd.isna(v):
+                    d[k] = None
+                else:
+                    d[k] = v
+            try:
+                return json.dumps(d, ensure_ascii=False)
+            except Exception:
+                # Fallback: stringify everything
+                return json.dumps({k: (None if v is None else str(v)) for k, v in d.items()}, ensure_ascii=False)
+
+        # ---------- Validate path and locate YAML/CSVs ----------
+        if not os.path.exists(path) or not os.path.isdir(path):
+            if not silent:
+                print("ByCSVPath - Error: path must be an existing folder. Returning None.")
+            return None
+
+        yaml_files = _find_yaml_files(path)
+        if len(yaml_files) < 1:
+            if not silent:
+                print("ByCSVPath - Error: no YAML file found in the folder. Returning None.")
+            return None
+        yaml_file = yaml_files[0]
+        graphs_rel, edges_rel, nodes_rel = _read_yaml(yaml_file)
+
+        # Resolve CSV paths
+        graphs_csv = os.path.join(path, graphs_rel) if graphs_rel else None
+        edges_csv = os.path.join(path, edges_rel) if edges_rel else None
+        nodes_csv = os.path.join(path, nodes_rel) if nodes_rel else None
+
+        if not edges_csv or not os.path.exists(edges_csv):
+            if not silent:
+                print("ByCSVPath - Error: edges CSV not found. Returning None.")
+            return None
+        if not nodes_csv or not os.path.exists(nodes_csv):
+            if not silent:
+                print("ByCSVPath - Error: nodes CSV not found. Returning None.")
+            return None
+
+        # ---------- Load CSVs ----------
+        nodes_df = pd.read_csv(nodes_csv)
+        edges_df = pd.read_csv(edges_csv)
+        graphs_df = pd.read_csv(graphs_csv) if graphs_csv and os.path.exists(graphs_csv) else pd.DataFrame()
+
+        # Required columns
+        for req_cols, df_name, df in [
+            ({graphIDHeader, nodeIDHeader}, "nodes", nodes_df),
+            ({graphIDHeader, edgeSRCHeader, edgeDSTHeader}, "edges", edges_df),
+        ]:
+            missing = req_cols.difference(df.columns)
+            if missing:
+                raise ValueError(f"ByCSVPath - {df_name}.csv is missing required columns: {missing}")
+
+        # Graph IDs present in the data
+        gids = pd.Index([]).union(nodes_df[graphIDHeader].dropna().unique()).union(
+            edges_df[graphIDHeader].dropna().unique()
+        )
+
+        # Prepare graphs_df lookup if provided
+        graphs_by_gid = {}
+        if graphIDHeader in graphs_df.columns:
+            graphs_by_gid = {gid: g.iloc[0].to_dict() for gid, g in graphs_df.groupby(graphIDHeader, dropna=False)}
+
+        # ---------- Ensure schema ----------
+        manager.ensure_schema()  # Graph, Vertex, Edge
+
+        # ---------- Upsert per graph ----------
+        materialized_graph_ids = []
+        for raw_gid in gids:
+            gid_str = f"{graphIDPrefix}{int(raw_gid) if str(raw_gid).isdigit() else str(raw_gid)}"
+            materialized_graph_ids.append(gid_str)
+
+            nsub = nodes_df[nodes_df[graphIDHeader] == raw_gid].copy()
+            esub = edges_df[edges_df[graphIDHeader] == raw_gid].copy()
+
+            # Graph info
+            gcard_src = graphs_by_gid.get(raw_gid, {})
+            g_label = str(gcard_src.get(graphLabelHeader, "")) if gcard_src else ""
+            g_props = _props_from_row(pd.Series(gcard_src), exclude={graphIDHeader, graphLabelHeader}) if gcard_src else "{}"
+            num_nodes = int(nsub.shape[0])
+            num_edges = int(esub.shape[0])
+
+            # Remove any existing data for this graph id, then re-insert
+            manager.exec("""
+                MATCH (a:Vertex)-[r:Edge]->(b:Vertex)
+                WHERE a.graph_id = $gid AND b.graph_id = $gid
+                DELETE r;
+            """, {"gid": gid_str}, write=True)
+            manager.exec("MATCH (v:Vertex) WHERE v.graph_id = $gid DELETE v;", {"gid": gid_str}, write=True)
+            manager.exec("MATCH (g:Graph) WHERE g.id = $gid DELETE g;", {"gid": gid_str}, write=True)
+
+            manager.exec("""
+                CREATE (g:Graph {id:$id, label:$label, num_nodes:$num_nodes, num_edges:$num_edges, props:$props});
+            """, {
+                "id": gid_str,
+                "label": g_label,
+                "num_nodes": num_nodes,
+                "num_edges": num_edges,
+                "props": g_props,
+            }, write=True)
+
+            # Insert vertices
+            for _, row in nsub.iterrows():
+                node_id = row[nodeIDHeader]
+                vid = f"{gid_str}:{node_id}"
+                v_label = str(row[nodeLabelHeader]) if "label" in row and pd.notna(row[nodeLabelHeader]) else str(node_id)
+
+                # X/Y/Z may be missing or non-numeric; store a random numeric value in that case
+                def _num_or_none(val):
+                    try:
+                        return float(val)
+                    except Exception:
+                        return None
+
+                x = _num_or_none(row[nodeXHeader]) if nodeXHeader in row else random.uniform(0,1000)
+                y = _num_or_none(row[nodeYHeader]) if nodeYHeader in row else random.uniform(0,1000)
+                z = _num_or_none(row[nodeZHeader]) if nodeZHeader in row else random.uniform(0,1000)
+
+                props = _props_from_row(row, exclude={graphIDHeader, nodeIDHeader, nodeLabelHeader, nodeXHeader, nodeYHeader, nodeZHeader})
+                manager.exec("""
+                    CREATE (v:Vertex {id:$id, graph_id:$gid, label:$label, x:$x, y:$y, z:$z, props:$props});
+                """, {"id": vid, "gid": gid_str, "label": v_label, "x": x, "y": y, "z": z, "props": props}, write=True)
+
+            # Insert edges (Edge)
+            for _, row in esub.iterrows():
+                a_id = f"{gid_str}:{row[edgeSRCHeader]}"
+                b_id = f"{gid_str}:{row[edgeDSTHeader]}"
+                e_label = str(row[edgeLabelHeader]) if edgeLabelHeader in row and pd.notna(row[edgeLabelHeader]) else "connect"
+                e_props = _props_from_row(row, exclude={graphIDHeader, edgeSRCHeader, edgeDSTHeader, edgeLabelHeader})
+
+                manager.exec("""
+                    MATCH (a:Vertex {id:$a_id}), (b:Vertex {id:$b_id})
+                    CREATE (a)-[:Edge {label:$label, props:$props}]->(b);
+                """, {"a_id": a_id, "b_id": b_id, "label": e_label, "props": e_props}, write=True)
+
+        return {"graphs_upserted": len(materialized_graph_ids), "graph_ids": materialized_graph_ids}
+
+
+