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

camel/models/deepseek_model.py

@@ -50,6 +50,11 @@ class DeepSeekModel(BaseModelBackend):
         https://api-docs.deepseek.com/
     """
 
+    @api_keys_required(
+        [
+            ("api_key", "DEEPSEEK_API_KEY"),
+        ]
+    )
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -90,7 +95,6 @@ class DeepSeekModel(BaseModelBackend):
             )
         return self._token_counter
 
-    @api_keys_required("DEEPSEEK_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/models/gemini_model.py

@@ -52,6 +52,11 @@ class GeminiModel(BaseModelBackend):
             (default: :obj:`None`)
     """
 
+    @api_keys_required(
+        [
+            ("api_key", 'GEMINI_API_KEY'),
+        ]
+    )
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -77,7 +82,6 @@ class GeminiModel(BaseModelBackend):
             base_url=self._url,
         )
 
-    @api_keys_required("GEMINI_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/models/groq_model.py

@@ -51,6 +51,11 @@ class GroqModel(BaseModelBackend):
             (default: :obj:`None`)
     """
 
+    @api_keys_required(
+        [
+            ("api_key", "GROQ_API_KEY"),
+        ]
+    )
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -89,7 +94,6 @@ class GroqModel(BaseModelBackend):
             self._token_counter = OpenAITokenCounter(ModelType.GPT_4O_MINI)
         return self._token_counter
 
-    @api_keys_required("GROQ_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/models/mistral_model.py

@@ -59,6 +59,11 @@ class MistralModel(BaseModelBackend):
             be used. (default: :obj:`None`)
     """
 
+    @api_keys_required(
+        [
+            ("api_key", "MISTRAL_API_KEY"),
+        ]
+    )
     @dependencies_required('mistralai')
     def __init__(
         self,
@@ -200,7 +205,6 @@ class MistralModel(BaseModelBackend):
             )
         return self._token_counter
 
-    @api_keys_required("MISTRAL_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/models/nemotron_model.py

@@ -40,6 +40,11 @@ class NemotronModel(BaseModelBackend):
         Nemotron model doesn't support additional model config like OpenAI.
     """
 
+    @api_keys_required(
+        [
+            ("api_key", "NVIDIA_API_KEY"),
+        ]
+    )
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -58,7 +63,6 @@ class NemotronModel(BaseModelBackend):
             api_key=self._api_key,
         )
 
-    @api_keys_required("NVIDIA_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/models/nvidia_model.py

@@ -48,6 +48,11 @@ class NvidiaModel(BaseModelBackend):
             (default: :obj:`None`)
     """
 
+    @api_keys_required(
+        [
+            ("api_key", "NVIDIA_API_KEY"),
+        ]
+    )
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -72,7 +77,6 @@ class NvidiaModel(BaseModelBackend):
             base_url=self._url,
         )
 
-    @api_keys_required("NVIDIA_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/models/openai_model.py

@@ -52,6 +52,11 @@ class OpenAIModel(BaseModelBackend):
             be used. (default: :obj:`None`)
     """
 
+    @api_keys_required(
+        [
+            ("api_key", "OPENAI_API_KEY"),
+        ]
+    )
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -86,7 +91,6 @@ class OpenAIModel(BaseModelBackend):
             self._token_counter = OpenAITokenCounter(self.model_type)
         return self._token_counter
 
-    @api_keys_required("OPENAI_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/models/qwen_model.py

@@ -52,6 +52,11 @@ class QwenModel(BaseModelBackend):
             (default: :obj:`None`)
     """
 
+    @api_keys_required(
+        [
+            ("api_key", "QWEN_API_KEY"),
+        ]
+    )
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -77,7 +82,6 @@ class QwenModel(BaseModelBackend):
             base_url=self._url,
         )
 
-    @api_keys_required("QWEN_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/models/reka_model.py

@@ -56,6 +56,11 @@ class RekaModel(BaseModelBackend):
             be used. (default: :obj:`None`)
     """
 
+    @api_keys_required(
+        [
+            ("api_key", "REKA_API_KEY"),
+        ]
+    )
     @dependencies_required('reka')
     def __init__(
         self,
@@ -168,7 +173,6 @@ class RekaModel(BaseModelBackend):
             )
         return self._token_counter
 
-    @api_keys_required("REKA_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/models/reward/nemotron_model.py

@@ -53,7 +53,11 @@ class NemotronRewardModel(BaseRewardModel):
             api_key=self.api_key,
         )
 
-    @api_keys_required("NVIDIA_API_KEY")
+    @api_keys_required(
+        [
+            (None, "NVIDIA_API_KEY"),
+        ]
+    )
     def evaluate(self, messages: List[Dict[str, str]]) -> Dict[str, float]:
         r"""Evaluate the messages using the Nemotron model.
 

camel/models/samba_model.py

@@ -74,6 +74,11 @@ class SambaModel(BaseModelBackend):
             ModelType.GPT_4O_MINI)` will be used.
     """
 
+    @api_keys_required(
+        [
+            ("api_key", 'SAMBA_API_KEY'),
+        ]
+    )
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -143,7 +148,6 @@ class SambaModel(BaseModelBackend):
                 " SambaNova service"
             )
 
-    @api_keys_required("SAMBA_API_KEY")
     def run(  # type: ignore[misc]
         self, messages: List[OpenAIMessage]
     ) -> Union[ChatCompletion, Stream[ChatCompletionChunk]]:

camel/models/togetherai_model.py

@@ -53,6 +53,11 @@ class TogetherAIModel(BaseModelBackend):
             ModelType.GPT_4O_MINI)` will be used.
     """
 
+    @api_keys_required(
+        [
+            ("api_key", 'TOGETHER_API_KEY'),
+        ]
+    )
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -78,7 +83,6 @@ class TogetherAIModel(BaseModelBackend):
             base_url=self._url,
         )
 
-    @api_keys_required("TOGETHER_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/models/yi_model.py

@@ -52,6 +52,11 @@ class YiModel(BaseModelBackend):
             (default: :obj:`None`)
     """
 
+    @api_keys_required(
+        [
+            ("api_key", 'YI_API_KEY'),
+        ]
+    )
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -76,7 +81,6 @@ class YiModel(BaseModelBackend):
             base_url=self._url,
         )
 
-    @api_keys_required("YI_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/models/zhipuai_model.py

@@ -52,6 +52,11 @@ class ZhipuAIModel(BaseModelBackend):
             (default: :obj:`None`)
     """
 
+    @api_keys_required(
+        [
+            ("api_key", 'ZHIPUAI_API_KEY'),
+        ]
+    )
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -76,7 +81,6 @@ class ZhipuAIModel(BaseModelBackend):
             base_url=self._url,
         )
 
-    @api_keys_required("ZHIPUAI_API_KEY")
     def run(
         self,
         messages: List[OpenAIMessage],

camel/schemas/openai_converter.py

@@ -53,6 +53,11 @@ class OpenAISchemaConverter(BaseConverter):
 
     """
 
+    @api_keys_required(
+        [
+            ("api_key", "OPENAI_API_KEY"),
+        ]
+    )
     def __init__(
         self,
         model_type: ModelType = ModelType.GPT_4O_MINI,
@@ -69,7 +74,6 @@ class OpenAISchemaConverter(BaseConverter):
         )._client
         super().__init__()
 
-    @api_keys_required("OPENAI_API_KEY")
     def convert(  # type: ignore[override]
         self,
         content: str,

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}")

camel/toolkits/__init__.py

@@ -28,6 +28,7 @@ from .ask_news_toolkit import AskNewsToolkit, AsyncAskNewsToolkit
 from .linkedin_toolkit import LinkedInToolkit
 from .reddit_toolkit import RedditToolkit
 from .meshy_toolkit import MeshyToolkit
+from .openbb_toolkit import OpenBBToolkit
 
 from .base import BaseToolkit
 from .google_maps_toolkit import GoogleMapsToolkit
@@ -43,6 +44,7 @@ from .notion_toolkit import NotionToolkit
 from .human_toolkit import HumanToolkit
 from .stripe_toolkit import StripeToolkit
 from .video_toolkit import VideoDownloaderToolkit
+from .dappier_toolkit import DappierToolkit
 
 __all__ = [
     'BaseToolkit',
@@ -73,4 +75,6 @@ __all__ = [
     'VideoDownloaderToolkit',
     'StripeToolkit',
     'MeshyToolkit',
+    'OpenBBToolkit',
+    'DappierToolkit',
 ]