camel-ai 0.2.15a0__py3-none-any.whl → 0.2.17__py3-none-any.whl

camel/storages/graph_storages/nebula_graph.py

@@ -15,7 +15,7 @@
 import logging
 import re
 import time
-from typing import TYPE_CHECKING, Any, Dict, List, Tuple
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
 
 from camel.storages.graph_storages.base import BaseGraphStorage
 from camel.storages.graph_storages.graph_element import (
@@ -203,46 +203,62 @@ class NebulaGraph(BaseGraphStorage):
     def ensure_edge_type_exists(
         self,
         edge_type: str,
+        time_label: Optional[str] = None,
     ) -> None:
         r"""Ensures that a specified edge type exists in the NebulaGraph
         database. If the edge type already exists, this method does nothing.
 
         Args:
             edge_type (str): The name of the edge type to be created.
+            time_label (str, optional): A specific timestamp to set as the
+                default value for the time label property. If not
+                provided, no timestamp will be added. (default: :obj:`None`)
 
         Raises:
             Exception: If the edge type creation fails after multiple retry
                 attempts, an exception is raised with the error message.
         """
-        create_edge_stmt = f'CREATE EDGE IF NOT EXISTS {edge_type}()'
+        create_edge_stmt = f"CREATE EDGE IF NOT EXISTS {edge_type} ()"
+        if time_label is not None:
+            time_label = self._validate_time_label(time_label)
+            create_edge_stmt = f"""CREATE EDGE IF NOT EXISTS {edge_type}
+            (time_label DATETIME DEFAULT {time_label})"""
 
         for attempt in range(MAX_RETRIES):
             res = self.query(create_edge_stmt)
             if res.is_succeeded():
-                return  # Tag creation succeeded, exit the method
+                return  # Edge type creation succeeded
 
             if attempt < MAX_RETRIES - 1:
                 time.sleep(RETRY_DELAY)
             else:
                 # Final attempt failed, raise an exception
                 raise Exception(
-                    f"Failed to create tag `{edge_type}` after "
+                    f"Failed to create edge type `{edge_type}` after "
                     f"{MAX_RETRIES} attempts: {res.error_msg()}"
                 )
 
-    def ensure_tag_exists(self, tag_name: str) -> None:
+    def ensure_tag_exists(
+        self, tag_name: str, time_label: Optional[str] = None
+    ) -> None:
         r"""Ensures a tag is created in the NebulaGraph database. If the tag
         already exists, it does nothing.
 
         Args:
             tag_name (str): The name of the tag to be created.
+            time_label (str, optional): A specific timestamp to set as the
+                default value for the time label property. If not provided,
+                no timestamp will be added. (default: :obj:`None`)
 
         Raises:
             Exception: If the tag creation fails after retries, an exception
                 is raised with the error message.
         """
-
-        create_tag_stmt = f'CREATE TAG IF NOT EXISTS {tag_name}()'
+        create_tag_stmt = f"CREATE TAG IF NOT EXISTS {tag_name} ()"
+        if time_label is not None:
+            time_label = self._validate_time_label(time_label)
+            create_tag_stmt = f"""CREATE TAG IF NOT EXISTS {tag_name}
+            (time_label DATETIME DEFAULT {time_label})"""
 
         for attempt in range(MAX_RETRIES):
             res = self.query(create_tag_stmt)
@@ -262,27 +278,39 @@ class NebulaGraph(BaseGraphStorage):
         self,
         node_id: str,
         tag_name: str,
+        time_label: Optional[str] = None,
     ) -> None:
         r"""Add a node with the specified tag and properties.
 
         Args:
             node_id (str): The ID of the node.
             tag_name (str): The tag name of the node.
+            time_label (str, optional): A specific timestamp to set for
+                the node's time label property. If not provided, no timestamp
+                will be added. (default: :obj:`None`)
         """
         node_id = re.sub(r'[^a-zA-Z0-9\u4e00-\u9fa5]', '', node_id)
         tag_name = re.sub(r'[^a-zA-Z0-9\u4e00-\u9fa5]', '', tag_name)
 
-        self.ensure_tag_exists(tag_name)
+        self.ensure_tag_exists(tag_name, time_label)
 
-        # Insert node without properties
-        insert_stmt = (
-            f'INSERT VERTEX IF NOT EXISTS {tag_name}() VALUES "{node_id}":()'
-        )
+        # Insert node with or without time_label property
+        if time_label is not None:
+            time_label = self._validate_time_label(time_label)
+            insert_stmt = (
+                f'INSERT VERTEX IF NOT EXISTS {tag_name}(time_label) VALUES '
+                f'"{node_id}":("{time_label}")'
+            )
+        else:
+            insert_stmt = (
+                f'INSERT VERTEX IF NOT EXISTS {tag_name}() VALUES '
+                f'"{node_id}":()'
+            )
 
         for attempt in range(MAX_RETRIES):
             res = self.query(insert_stmt)
             if res.is_succeeded():
-                return  # Tag creation succeeded, exit the method
+                return  # Node creation succeeded, exit the method
 
             if attempt < MAX_RETRIES - 1:
                 time.sleep(RETRY_DELAY)
@@ -348,7 +376,7 @@ class NebulaGraph(BaseGraphStorage):
     @property
     def get_structured_schema(self) -> Dict[str, Any]:
         r"""Generates a structured schema consisting of node and relationship
-        properties, relationships, and metadata.
+        properties, relationships, and metadata, including timestamps.
 
         Returns:
             Dict[str, Any]: A dictionary representing the structured schema.
@@ -419,6 +447,7 @@ class NebulaGraph(BaseGraphStorage):
         subj: str,
         obj: str,
         rel: str,
+        time_label: Optional[str] = None,
     ) -> None:
         r"""Adds a relationship (triplet) between two entities in the Nebula
         Graph database.
@@ -427,6 +456,13 @@ class NebulaGraph(BaseGraphStorage):
             subj (str): The identifier for the subject entity.
             obj (str): The identifier for the object entity.
             rel (str): The relationship between the subject and object.
+            time_label (str, optional): A specific timestamp to set for the
+                time label property of the relationship. If not provided,
+                no timestamp will be added. (default: :obj:`None`)
+
+        Raises:
+            ValueError: If the time_label format is invalid.
+            Exception: If creating the relationship fails.
         """
         subj = re.sub(r'[^a-zA-Z0-9\u4e00-\u9fa5]', '', subj)
         obj = re.sub(r'[^a-zA-Z0-9\u4e00-\u9fa5]', '', obj)
@@ -434,21 +470,30 @@ class NebulaGraph(BaseGraphStorage):
 
         self.ensure_tag_exists(subj)
         self.ensure_tag_exists(obj)
-        self.ensure_edge_type_exists(rel)
+        self.ensure_edge_type_exists(rel, time_label)
         self.add_node(node_id=subj, tag_name=subj)
         self.add_node(node_id=obj, tag_name=obj)
 
-        # Avoid latenicy
+        # Avoid latency
         time.sleep(1)
 
-        insert_stmt = (
-            f'INSERT EDGE IF NOT EXISTS {rel}() VALUES "{subj}"->"{obj}":();'
-        )
+        # Create edge with or without time_label property
+        if time_label is not None:
+            time_label = self._validate_time_label(time_label)
+            insert_stmt = (
+                f'INSERT EDGE IF NOT EXISTS {rel}(time_label) VALUES '
+                f'"{subj}"->"{obj}":("{time_label}")'
+            )
+        else:
+            insert_stmt = (
+                f'INSERT EDGE IF NOT EXISTS {rel}() VALUES '
+                f'"{subj}"->"{obj}":()'
+            )
 
         res = self.query(insert_stmt)
         if not res.is_succeeded():
             raise Exception(
-                f'create relationship `]{subj}` -> `{obj}`'
+                f'create relationship `{subj}` -> `{obj}`'
                 + f'failed: {res.error_msg()}'
             )
 
@@ -568,3 +613,27 @@ class NebulaGraph(BaseGraphStorage):
             )
 
         return rel_schema_props, rel_structure_props
+
+    def _validate_time_label(self, time_label: str) -> str:
+        r"""Validates the format of a time label string.
+
+        Args:
+            time_label (str): The time label string to validate.
+                Should be in format 'YYYY-MM-DDThh:mm:ss'.
+
+        Returns:
+            str: The validated time label.
+
+        Raises:
+            ValueError: If the time label format is invalid.
+        """
+        try:
+            # Check if the format matches YYYY-MM-DDThh:mm:ss
+            pattern = r'^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$'
+            if not re.match(pattern, time_label):
+                raise ValueError(
+                    "Time label must be in format 'YYYY-MM-DDThh:mm:ss'"
+                )
+            return time_label
+        except Exception as e:
+            raise ValueError(f"Invalid time label format: {e!s}")

camel/storages/graph_storages/neo4j_graph.py

@@ -583,3 +583,141 @@ class Neo4jGraph(BaseGraphStorage):
                     ]
                 },
             )
+
+    def random_walk_with_restarts(
+        self,
+        graph_name: str,
+        sampling_ratio: float,
+        start_node_ids: List[int],
+        restart_probability: float = 0.1,
+        node_label_stratification: bool = False,
+        relationship_weight_property: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        r"""Runs the Random Walk with Restarts (RWR) sampling algorithm.
+
+        Args:
+            graph_name (str): The name of the original graph in the graph
+                catalog.
+            sampling_ratio (float): The fraction of nodes in the original
+                graph to be sampled.
+            start_node_ids (List[int]): IDs of the initial set of nodes of the
+                original graph from which the sampling random walks will start.
+            restart_probability (float, optional): The probability that a
+                sampling random walk restarts from one of the start nodes.
+                Defaults to `0.1`.
+            node_label_stratification (bool, optional): If true, preserves the
+                node label distribution of the original graph. Defaults to
+                `False`.
+            relationship_weight_property (Optional[str], optional): Name of
+                the relationship property to use as weights. If unspecified,
+                the algorithm runs unweighted. Defaults to `None`.
+
+        Returns:
+            Dict[str, Any]: A dictionary with the results of the RWR sampling.
+        """
+        from neo4j.exceptions import ClientError, CypherSyntaxError
+
+        try:
+            self.query(query="CALL gds.version() YIELD version RETURN version")
+        except ClientError:
+            raise ValueError(
+                "Graph Data Science (GDS) library is not installed or not"
+                " available. Reference: https://neo4j.com/docs/graph-data-science/current/installation/"
+            )
+
+        query = """
+        CALL gds.graph.sample.rwr($graphName, $fromGraphName, {
+            samplingRatio: $samplingRatio,
+            startNodes: $startNodes,
+            restartProbability: $restartProbability,
+            nodeLabelStratification: $nodeLabelStratification,
+            relationshipWeightProperty: $relationshipWeightProperty
+        })
+        YIELD graphName, fromGraphName, nodeCount, 
+        relationshipCount, startNodeCount, projectMillis
+        RETURN graphName, fromGraphName, nodeCount, 
+        relationshipCount, startNodeCount, projectMillis
+        """
+
+        params = {
+            "graphName": f"{graph_name}_sampled",
+            "fromGraphName": graph_name,
+            "samplingRatio": sampling_ratio,
+            "startNodes": start_node_ids,
+            "restartProbability": restart_probability,
+            "nodeLabelStratification": node_label_stratification,
+            "relationshipWeightProperty": relationship_weight_property,
+        }
+
+        try:
+            result = self.query(query, params)
+            return result[0] if result else {}
+        except CypherSyntaxError as e:
+            raise ValueError(f"Generated Cypher Statement is not valid\n{e}")
+
+    def common_neighbour_aware_random_walk(
+        self,
+        graph_name: str,
+        sampling_ratio: float,
+        start_node_ids: List[int],
+        node_label_stratification: bool = False,
+        relationship_weight_property: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        r"""Runs the Common Neighbour Aware Random Walk (CNARW) sampling
+        algorithm.
+
+        Args:
+            graph_name (str): The name of the original graph in the graph
+                catalog.
+            sampling_ratio (float): The fraction of nodes in the original
+                graph to be sampled.
+            start_node_ids (List[int]): IDs of the initial set of nodes of the
+                original graph from which the sampling random walks will start.
+            node_label_stratification (bool, optional): If true, preserves the
+                node label distribution of the original graph. Defaults to
+                `False`.
+            relationship_weight_property (Optional[str], optional): Name of
+                the relationship property to use as weights. If unspecified,
+                the algorithm runs unweighted. Defaults to `None`.
+
+        Returns:
+            Dict[str, Any]: A dictionary with the results of the CNARW
+                sampling.
+        """
+        from neo4j.exceptions import ClientError, CypherSyntaxError
+
+        try:
+            self.query(query="CALL gds.version() YIELD version RETURN version")
+        except ClientError:
+            raise ValueError(
+                "Graph Data Science (GDS) library is not installed or not"
+                " available. Reference: https://neo4j.com/docs/graph-data-science/current/installation/"
+            )
+
+        query = """
+        CALL gds.graph.sample.cnarw($graphName, $fromGraphName, {
+            samplingRatio: $samplingRatio,
+            startNodes: $startNodes,
+            nodeLabelStratification: $nodeLabelStratification,
+            relationshipWeightProperty: $relationshipWeightProperty
+        })
+        YIELD graphName, fromGraphName, nodeCount, 
+        relationshipCount, startNodeCount, projectMillis
+        RETURN graphName, fromGraphName, nodeCount, 
+        relationshipCount, startNodeCount, projectMillis
+        """
+
+        params = {
+            "graphName": f"{graph_name}_sampled_cnarw",
+            "fromGraphName": graph_name,
+            "samplingRatio": sampling_ratio,
+            "startNodes": start_node_ids,
+            "nodeLabelStratification": node_label_stratification,
+            "relationshipWeightProperty": relationship_weight_property,
+        }
+
+        try:
+            result = self.query(query, params)
+            return result[0] if result else {}
+        except CypherSyntaxError as e:
+            raise ValueError(f"Generated Cypher Statement is not valid\n{e}")