camel-ai 0.2.14__py3-none-any.whl → 0.2.16__py3-none-any.whl

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',
 ]

camel/toolkits/arxiv_toolkit.py

@@ -14,10 +14,13 @@
 
 from typing import Dict, Generator, List, Optional
 
+from camel.logger import get_logger
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
 from camel.utils import dependencies_required
 
+logger = get_logger(__name__)
+
 
 class ArxivToolkit(BaseToolkit):
     r"""A toolkit for interacting with the arXiv API to search and download
@@ -98,10 +101,24 @@ class ArxivToolkit(BaseToolkit):
                 "authors": [author.name for author in paper.authors],
                 "entry_id": paper.entry_id,
                 "summary": paper.summary,
-                # TODO: Use chunkr instead of atxiv_to_text for better
-                # performance
-                "paper_text": arxiv_to_text(paper.pdf_url),
+                "pdf_url": paper.pdf_url,
             }
+
+            # Extract text from the paper
+            try:
+                # TODO: Use chunkr instead of atxiv_to_text for better
+                # performance and reliability
+                text = arxiv_to_text(paper_info["pdf_url"])
+            except Exception as e:
+                logger.error(
+                    "Failed to extract text content from the PDF at "
+                    "the specified URL. "
+                    f"URL: {paper_info.get('pdf_url', 'Unknown')} | Error: {e}"
+                )
+                text = ""
+
+            paper_info['paper_text'] = text
+
             papers_data.append(paper_info)
 
         return papers_data

camel/toolkits/dappier_toolkit.py

@@ -0,0 +1,196 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import os
+from typing import Dict, List, Literal, Optional, Union
+
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+from camel.utils import api_keys_required, dependencies_required
+
+
+class DappierToolkit(BaseToolkit):
+    r"""A class representing a toolkit for interacting with the Dappier API.
+
+    This class provides methods for searching real time data and fetching
+    ai recommendations across key verticals like News, Finance, Stock Market,
+    Sports, Weather and more.
+    """
+
+    @dependencies_required("dappier")
+    @api_keys_required(
+        [
+            (None, "DAPPIER_API_KEY"),
+        ]
+    )
+    def __init__(self):
+        r"""Initialize the DappierTookit with API clients.The API keys and
+        credentials are retrieved from environment variables.
+        """
+        from dappier import Dappier
+
+        dappier_api_key = os.environ.get("DAPPIER_API_KEY")
+
+        self.dappier_client = Dappier(dappier_api_key)
+
+    def search_real_time_data(
+        self, query: str, ai_model_id: str = "am_01j06ytn18ejftedz6dyhz2b15"
+    ) -> str:
+        r"""Search real-time data using an AI model.
+
+        This function accesses real-time information using the specified
+        AI model based on the given query. Depending on the AI model ID,
+        the data retrieved can vary between general web search results or
+        financial news and stock prices.
+
+        Supported AI Models:
+            - `am_01j06ytn18ejftedz6dyhz2b15`:
+            Access real-time Google web search results, including the latest
+            news, weather updates, travel details, deals, and more.
+            - `am_01j749h8pbf7ns8r1bq9s2evrh`:
+            Access real-time financial news, stock prices, and trades from
+            polygon.io, with AI-powered insights and up-to-the-minute updates.
+
+        Args:
+            query (str): The user-provided query. Examples include:
+                - "How is the weather today in Austin, TX?"
+                - "What is the latest news for Meta?"
+                - "What is the stock price for AAPL?"
+            ai_model_id (str, optional): The AI model ID to use for the query.
+                The AI model ID always starts with the prefix "am_".
+                (default: `am_01j06ytn18ejftedz6dyhz2b15`)
+
+        Returns:
+            str: The search result corresponding to the provided query and
+                AI model ID. This may include real time search data,
+                depending on the selected AI model.
+
+        Note:
+            Multiple AI model IDs are available, which can be found at:
+            https://marketplace.dappier.com/marketplace
+        """
+        try:
+            response = self.dappier_client.search_real_time_data(
+                query=query, ai_model_id=ai_model_id
+            )
+
+            if response is None:
+                return "An unknown error occurred"
+
+            return response.message
+
+        except Exception as e:
+            return f"An unexpected error occurred: {e}"
+
+    def get_ai_recommendations(
+        self,
+        query: str,
+        data_model_id: str = "dm_01j0pb465keqmatq9k83dthx34",
+        similarity_top_k: int = 9,
+        ref: Optional[str] = None,
+        num_articles_ref: int = 0,
+        search_algorithm: Literal[
+            "most_recent", "semantic", "most_recent_semantic", "trending"
+        ] = "most_recent",
+    ) -> Union[List[Dict[str, str]], Dict[str, str]]:
+        r"""Retrieve AI-powered recommendations based on the provided query
+        and data model.
+
+        This function fetches real-time AI-generated recommendations using the
+        specified data model and search algorithm. The results include
+        personalized content based on the query and, optionally, relevance
+        to a specific reference domain.
+
+        Supported Data Models:
+            - `dm_01j0pb465keqmatq9k83dthx34`:
+            Real-time news, updates, and personalized content from top sports
+            sources such as Sportsnaut, Forever Blueshirts, Minnesota Sports
+            Fan, LAFB Network, Bounding Into Sports, and Ringside Intel.
+            - `dm_01j0q82s4bfjmsqkhs3ywm3x6y`:
+            Real-time updates, analysis, and personalized content from top
+            sources like The Mix, Snipdaily, Nerdable, and Familyproof.
+
+        Args:
+            query (str): The user query for retrieving recommendations.
+            data_model_id (str, optional): The data model ID to use for
+                recommendations. Data model IDs always start with the prefix
+                "dm_". (default: :obj: `dm_01j0pb465keqmatq9k83dthx34`)
+            similarity_top_k (int, optional): The number of top documents to
+                retrieve based on similarity. (default: :obj: `9`)
+            ref (Optional[str], optional): The site domain where AI
+                recommendations should be displayed. (default: :obj: `None`)
+            num_articles_ref (int, optional): The minimum number of articles
+                to return from the specified reference domain (`ref`). The
+                remaining articles will come from other sites in the RAG
+                model. (default: :obj: `0`)
+            search_algorithm (Literal[
+                "most_recent",
+                "semantic",
+                "most_recent_semantic",
+                "trending",
+                ], optional): The search algorithm to use for retrieving
+                articles. (default: :obj: `most_recent`)
+
+        Returns:
+            List[Dict[str, str]]: A list of recommended articles or content
+                based on the specified parameters, query, and data model.
+
+        Note:
+            Multiple data model IDs are available and can be found at:
+            https://marketplace.dappier.com/marketplace
+        """
+        try:
+            response = self.dappier_client.get_ai_recommendations(
+                query=query,
+                data_model_id=data_model_id,
+                similarity_top_k=similarity_top_k,
+                ref=ref,
+                num_articles_ref=num_articles_ref,
+                search_algorithm=search_algorithm,
+            )
+
+            if response is None or response.status != "success":
+                return {"error": "An unknown error occurred."}
+
+            # Collect only relevant information from the response.
+            results = [
+                {
+                    "author": result.author,
+                    "image_url": result.image_url,
+                    "pubdate": result.pubdate,
+                    "source_url": result.source_url,
+                    "summary": result.summary,
+                    "title": result.title,
+                }
+                for result in (
+                    getattr(response.response, "results", None) or []
+                )
+            ]
+
+            return results
+
+        except Exception as e:
+            return {"error": f"An unexpected error occurred: {e!s}"}
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Returns a list of FunctionTool objects representing the functions
+        in the toolkit.
+
+        Returns:
+            List[FunctionTool]: A list of FunctionTool objects representing
+                the functions in the toolkit.
+        """
+        return [
+            FunctionTool(self.search_real_time_data),
+            FunctionTool(self.get_ai_recommendations),
+        ]

camel/toolkits/function_tool.py

@@ -14,6 +14,7 @@
 import ast
 import inspect
 import logging
+import textwrap
 import warnings
 from inspect import Parameter, getsource, signature
 from typing import Any, Callable, Dict, Mapping, Optional, Tuple, Type
@@ -24,7 +25,6 @@ from jsonschema.validators import Draft202012Validator as JSONValidator
 from pydantic import BaseModel, create_model
 from pydantic.fields import FieldInfo
 
-from camel.agents import ChatAgent
 from camel.models import BaseModelBackend, ModelFactory
 from camel.types import ModelPlatformType, ModelType
 from camel.utils import get_pydantic_object_schema, to_pascal
@@ -237,41 +237,43 @@ def generate_docstring(
     Returns:
         str: The generated docstring.
     """
-    # Create the docstring prompt
-    docstring_prompt = '''
-    **Role**: Generate professional Python docstrings conforming to 
-    PEP 8/PEP 257.
 
-    **Requirements**:
-    - Use appropriate format: reST, Google, or NumPy, as needed.
-    - Include parameters, return values, and exceptions.
-    - Reference any existing docstring in the function and 
-      retain useful information.
+    from camel.agents import ChatAgent
 
-    **Input**: Python function.
+    # Create the docstring prompt
+    docstring_prompt = textwrap.dedent(
+        """\
+        **Role**: Generate professional Python docstrings conforming to PEP 8/PEP 257.
 
-    **Output**: Docstring content (plain text, no code markers).
+        **Requirements**:
+        - Use appropriate format: reST, Google, or NumPy, as needed.
+        - Include parameters, return values, and exceptions.
+        - Reference any existing docstring in the function and retain useful information.
 
-    **Example:**
+        **Input**: Python function.
 
-    Input:
-    ```python
-    def add(a: int, b: int) -> int:
-        return a + b
-    ```
+        **Output**: Docstring content (plain text, no code markers).
 
-    Output:
-    Adds two numbers.
-    Args:
-        a (int): The first number.
-        b (int): The second number.
+        **Example:**
 
-    Returns:
-        int: The sum of the two numbers.
+        Input:
+        ```python
+        def add(a: int, b: int) -> int:
+            return a + b
+        ```
 
-    **Task**: Generate a docstring for the function below.
+        Output:
+        Adds two numbers.
+        Args:
+            a (int): The first number.
+            b (int): The second number.
+
+        Returns:
+            int: The sum of the two numbers.
 
-    '''
+        **Task**: Generate a docstring for the function below.
+        """  # noqa: E501
+    )
     # Initialize assistant with system message and model
     assistant_sys_msg = "You are a helpful assistant."
     docstring_assistant = ChatAgent(assistant_sys_msg, model=model)
@@ -665,7 +667,7 @@ class FunctionTool:
             Any: Synthesized output from the function execution. If no
                 synthesis model is provided, a warning is logged.
         """
-        import textwrap
+        from camel.agents import ChatAgent
 
         # Retrieve the function source code
         function_string = inspect.getsource(self.func)
@@ -694,39 +696,37 @@ class FunctionTool:
             function_string += f"\nkwargs:\n{kwargs}"
 
         # Define the assistant system message
-        assistant_sys_msg = '''
-**Role:** AI Assistant specialized in synthesizing tool execution outputs
-without actual execution.
-
-**Capabilities:**
-- Analyzes function to understand their
-  purpose and expected outputs.
-- Generates synthetic outputs based on the function logic.
-- Ensures the synthesized output is contextually accurate and aligns with the
-  function's intended behavior.
-
-**Instructions:**
-1. **Input:** Provide the function code, function docstring, args, and kwargs.
-2. **Output:** Synthesize the expected output of the function based on the
-   provided args and kwargs.
-
-**Example:**
-- **User Input:**
-def sum(a, b, c=0):
-    """Adds three numbers together."""
-    return a + b + c
-
-- **Input Arguments:**
-args: (1, 2)
-kwargs: {"c": 3}
-
-- **Output:**
-6
-
-**Note:**
-- Just return the synthesized output of the function without any explanation.
-- The output should be in plain text without any formatting.
-'''
+        assistant_sys_msg = textwrap.dedent(
+            '''\
+            **Role:** AI Assistant specialized in synthesizing tool execution outputs without actual execution.
+
+            **Capabilities:**
+            - Analyzes function to understand their purpose and expected outputs.
+            - Generates synthetic outputs based on the function logic.
+            - Ensures the synthesized output is contextually accurate and aligns with the function's intended behavior.
+
+            **Instructions:**
+            1. **Input:** Provide the function code, function docstring, args, and kwargs.
+            2. **Output:** Synthesize the expected output of the function based on the provided args and kwargs.
+
+            **Example:**
+            - **User Input:**
+            def sum(a, b, c=0):
+                """Adds three numbers together."""
+                return a + b + c
+
+            - **Input Arguments:**
+            args: (1, 2)
+            kwargs: {"c": 3}
+
+            - **Output:**
+            6
+
+            **Note:**
+            - Just return the synthesized output of the function without any explanation.
+            - The output should be in plain text without any formatting.
+            '''  # noqa: E501
+        )
 
         # Initialize the synthesis agent
         synthesis_agent = ChatAgent(

camel/toolkits/meshy_toolkit.py

@@ -33,7 +33,11 @@ class MeshyToolkit(BaseToolkit):
     https://docs.meshy.ai/api-text-to-3d-beta#create-a-text-to-3d-preview-task
     """
 
-    @api_keys_required("MESHY_API_KEY")
+    @api_keys_required(
+        [
+            (None, 'MESHY_API_KEY'),
+        ]
+    )
     def __init__(self):
         r"""Initializes the MeshyToolkit with the API key from the
         environment.

camel/toolkits/notion_toolkit.py

@@ -71,7 +71,7 @@ class NotionToolkit(BaseToolkit):
 
     Attributes:
         notion_token (Optional[str], optional): The notion_token used to
-            interact with notion APIs.(default: :obj:`None`)
+            interact with notion APIs. (default: :obj:`None`)
         notion_client (module): The notion module for interacting with
             the notion APIs.
     """