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

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/google_scholar_toolkit.py

@@ -36,6 +36,7 @@ class GoogleScholarToolkit(BaseToolkit):
         self,
         author_identifier: str,
         is_author_name: bool = False,
+        use_free_proxies: bool = False,
         proxy_http: Optional[str] = None,
         proxy_https: Optional[str] = None,
     ) -> None:
@@ -46,6 +47,8 @@ class GoogleScholarToolkit(BaseToolkit):
                 of the author to search for.
             is_author_name (bool): Flag to indicate if the identifier is a
                 name. (default: :obj:`False`)
+            use_free_proxies (bool): Whether to use Free Proxies.
+                (default: :obj:`False`)
             proxy_http ( Optional[str]): Proxy http address pass to pg.
                 SingleProxy. (default: :obj:`None`)
             proxy_https ( Optional[str]): Proxy https address pass to pg.
@@ -53,6 +56,12 @@ class GoogleScholarToolkit(BaseToolkit):
         """
         from scholarly import ProxyGenerator, scholarly
 
+        # Set Free Proxies is needed
+        if use_free_proxies:
+            pg = ProxyGenerator()
+            pg.FreeProxies()
+            scholarly.use_proxy(pg)
+
         # Set Proxy is HTTP or HTTPS provided
         if proxy_http or proxy_https:
             pg = ProxyGenerator()

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.
     """