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

camel/toolkits/search_toolkit.py

@@ -13,9 +13,10 @@
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import os
 import xml.etree.ElementTree as ET
-from typing import Any, Dict, List, Optional, TypeAlias, Union
+from typing import Any, Dict, List, Literal, Optional, Type, TypeAlias, Union
 
 import requests
+from pydantic import BaseModel
 
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
@@ -63,6 +64,82 @@ class SearchToolkit(BaseToolkit):
 
         return result
 
+    @dependencies_required("linkup")
+    @api_keys_required(
+        [
+            (None, "LINKUP_API_KEY"),
+        ]
+    )
+    def search_linkup(
+        self,
+        query: str,
+        depth: Literal["standard", "deep"] = "standard",
+        output_type: Literal[
+            "searchResults", "sourcedAnswer", "structured"
+        ] = "searchResults",
+        structured_output_schema: Union[Type[BaseModel], str, None] = None,
+    ) -> Dict[str, Any]:
+        r"""Search for a query in the Linkup API and return results in various
+        formats.
+
+        Args:
+            query (str): The search query.
+            depth (Literal["standard", "deep"]): The depth of the search.
+                "standard" for a straightforward search, "deep" for a more
+                comprehensive search.
+            output_type (Literal["searchResults", "sourcedAnswer",
+                "structured"]): The type of output:
+                - "searchResults" for raw search results,
+                - "sourcedAnswer" for an answer with supporting sources,
+                - "structured" for output based on a provided schema.
+            structured_output_schema (Union[Type[BaseModel], str, None]): If
+                `output_type` is "structured",specify the schema of the
+                output. Can be a Pydantic BaseModel or a JSON schema string.
+
+        Returns:
+            Dict[str, Any]: A dictionary representing the search result. The
+                structure depends on the `output_type`. If an error occurs,
+                returns an error message.
+        """
+        try:
+            from linkup import LinkupClient
+
+            # Initialize the Linkup client with the API key
+            LINKUP_API_KEY = os.getenv("LINKUP_API_KEY")
+            client = LinkupClient(api_key=LINKUP_API_KEY)
+
+            # Perform the search using the specified output_type
+            response = client.search(
+                query=query,
+                depth=depth,
+                output_type=output_type,
+                structured_output_schema=structured_output_schema,
+            )
+
+            if output_type == "searchResults":
+                results = [
+                    item.__dict__
+                    for item in response.__dict__.get('results', [])
+                ]
+                return {"results": results}
+
+            elif output_type == "sourcedAnswer":
+                answer = response.__dict__.get('answer', '')
+                sources = [
+                    item.__dict__
+                    for item in response.__dict__.get('sources', [])
+                ]
+                return {"answer": answer, "sources": sources}
+
+            elif output_type == "structured" and structured_output_schema:
+                return response.__dict__
+
+            else:
+                return {"error": f"Invalid output_type: {output_type}"}
+
+        except Exception as e:
+            return {"error": f"An unexpected error occurred: {e!s}"}
+
     @dependencies_required("duckduckgo_search")
     def search_duckduckgo(
         self, query: str, source: str = "text", max_results: int = 5
@@ -151,7 +228,11 @@ class SearchToolkit(BaseToolkit):
         # If no answer found, return an empty list
         return responses
 
-    @api_keys_required("BRAVE_API_KEY")
+    @api_keys_required(
+        [
+            (None, 'BRAVE_API_KEY'),
+        ]
+    )
     def search_brave(
         self,
         q: str,
@@ -297,7 +378,12 @@ class SearchToolkit(BaseToolkit):
         data = response.json()["web"]
         return data
 
-    @api_keys_required("GOOGLE_API_KEY", "SEARCH_ENGINE_ID")
+    @api_keys_required(
+        [
+            (None, 'GOOGLE_API_KEY'),
+            (None, 'SEARCH_ENGINE_ID'),
+        ]
+    )
     def search_google(
         self, query: str, num_result_pages: int = 5
     ) -> List[Dict[str, Any]]:
@@ -429,8 +515,7 @@ class SearchToolkit(BaseToolkit):
         if not WOLFRAMALPHA_APP_ID:
             raise ValueError(
                 "`WOLFRAMALPHA_APP_ID` not found in environment "
-                "variables. Get `WOLFRAMALPHA_APP_ID` here: "
-                "`https://products.wolframalpha.com/api/`."
+                "variables. Get `WOLFRAMALPHA_APP_ID` here: `https://products.wolframalpha.com/api/`."
             )
 
         try:
@@ -618,6 +703,7 @@ class SearchToolkit(BaseToolkit):
         """
         return [
             FunctionTool(self.search_wiki),
+            FunctionTool(self.search_linkup),
             FunctionTool(self.search_google),
             FunctionTool(self.search_duckduckgo),
             FunctionTool(self.query_wolfram_alpha),

camel/toolkits/stripe_toolkit.py

@@ -36,7 +36,11 @@ class StripeToolkit(BaseToolkit):
         logger (Logger): a logger to write logs.
     """
 
-    @api_keys_required("STRIPE_API_KEY")
+    @api_keys_required(
+        [
+            (None, "STRIPE_API_KEY"),
+        ]
+    )
     def __init__(self, retries: int = 3):
         r"""Initializes the StripeToolkit with the specified number of
         retries.

camel/toolkits/twitter_toolkit.py

@@ -31,10 +31,12 @@ logger = get_logger(__name__)
 
 
 @api_keys_required(
-    "TWITTER_CONSUMER_KEY",
-    "TWITTER_CONSUMER_SECRET",
-    "TWITTER_ACCESS_TOKEN",
-    "TWITTER_ACCESS_TOKEN_SECRET",
+    [
+        (None, "TWITTER_CONSUMER_KEY"),
+        (None, "TWITTER_CONSUMER_SECRET"),
+        (None, "TWITTER_ACCESS_TOKEN"),
+        (None, "TWITTER_ACCESS_TOKEN_SECRET"),
+    ]
 )
 def create_tweet(
     text: str,
@@ -132,10 +134,12 @@ def create_tweet(
 
 
 @api_keys_required(
-    "TWITTER_CONSUMER_KEY",
-    "TWITTER_CONSUMER_SECRET",
-    "TWITTER_ACCESS_TOKEN",
-    "TWITTER_ACCESS_TOKEN_SECRET",
+    [
+        (None, "TWITTER_CONSUMER_KEY"),
+        (None, "TWITTER_CONSUMER_SECRET"),
+        (None, "TWITTER_ACCESS_TOKEN"),
+        (None, "TWITTER_ACCESS_TOKEN_SECRET"),
+    ]
 )
 def delete_tweet(tweet_id: str) -> str:
     r"""Deletes a tweet with the specified ID for an authorized user.
@@ -187,10 +191,12 @@ def delete_tweet(tweet_id: str) -> str:
 
 
 @api_keys_required(
-    "TWITTER_CONSUMER_KEY",
-    "TWITTER_CONSUMER_SECRET",
-    "TWITTER_ACCESS_TOKEN",
-    "TWITTER_ACCESS_TOKEN_SECRET",
+    [
+        (None, "TWITTER_CONSUMER_KEY"),
+        (None, "TWITTER_CONSUMER_SECRET"),
+        (None, "TWITTER_ACCESS_TOKEN"),
+        (None, "TWITTER_ACCESS_TOKEN_SECRET"),
+    ]
 )
 def get_my_user_profile() -> str:
     r"""Retrieves the authenticated user's Twitter profile info.
@@ -214,10 +220,12 @@ def get_my_user_profile() -> str:
 
 
 @api_keys_required(
-    "TWITTER_CONSUMER_KEY",
-    "TWITTER_CONSUMER_SECRET",
-    "TWITTER_ACCESS_TOKEN",
-    "TWITTER_ACCESS_TOKEN_SECRET",
+    [
+        (None, "TWITTER_CONSUMER_KEY"),
+        (None, "TWITTER_CONSUMER_SECRET"),
+        (None, "TWITTER_ACCESS_TOKEN"),
+        (None, "TWITTER_ACCESS_TOKEN_SECRET"),
+    ]
 )
 def get_user_by_username(username: str) -> str:
     r"""Retrieves one user's Twitter profile info by username (handle).

camel/utils/__init__.py

@@ -19,6 +19,7 @@ from .commons import (
     check_server_running,
     create_chunks,
     dependencies_required,
+    download_github_subdirectory,
     download_tasks,
     func_string_to_callable,
     generate_prompt_for_structured_output,
@@ -79,5 +80,6 @@ __all__ = [
     "track_agent",
     "handle_http_error",
     "get_pydantic_model",
+    "download_github_subdirectory",
     "generate_prompt_for_structured_output",
 ]

camel/utils/commons.py

@@ -21,6 +21,7 @@ import time
 import zipfile
 from functools import wraps
 from http import HTTPStatus
+from pathlib import Path
 from typing import (
     Any,
     Callable,
@@ -29,6 +30,7 @@ from typing import (
     Mapping,
     Optional,
     Set,
+    Tuple,
     Type,
     TypeVar,
     cast,
@@ -231,41 +233,79 @@ def is_module_available(module_name: str) -> bool:
         return False
 
 
-def api_keys_required(*required_keys: str) -> Callable[[F], F]:
-    r"""A decorator to check if the required API keys are
-    presented in the environment variables or as an instance attribute.
+def api_keys_required(
+    param_env_list: List[Tuple[Optional[str], str]],
+) -> Callable[[F], F]:
+    r"""A decorator to check if the required API keys are provided in the
+    environment variables or as function arguments.
 
     Args:
-        required_keys (str): The required API keys to be checked.
+        param_env_list (List[Tuple[Optional[str], str]]): A list of tuples
+            where each tuple contains a function argument name (as the first
+            element, or None) and the corresponding environment variable name
+            (as the second element) that holds the API key.
 
     Returns:
-        Callable[[F], F]: The original function with the added check
-            for required API keys.
+        Callable[[F], F]: The original function wrapped with the added check
+            for the required API keys.
 
     Raises:
-        ValueError: If any of the required API keys are missing in the
-            environment variables and the instance attribute.
+        ValueError: If any of the required API keys are missing, either
+            from the function arguments or environment variables.
 
     Example:
         ::
 
-            @api_keys_required('API_KEY_1', 'API_KEY_2')
-            def some_api_function():
-                # Function implementation...
+            @api_keys_required([
+                ('api_key_arg', 'API_KEY_1'),
+                ('another_key_arg', 'API_KEY_2'),
+                (None, 'API_KEY_3'),
+            ])
+            def some_api_function(api_key_arg=None, another_key_arg=None):
+                # Function implementation that requires API keys
     """
+    import inspect
 
     def decorator(func: F) -> F:
         @wraps(func)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
-            missing_environment_keys = [
-                k for k in required_keys if k not in os.environ
-            ]
-            if (
-                not (args and getattr(args[0], '_api_key', None))
-                and missing_environment_keys
-            ):
+            signature = inspect.signature(func)
+            bound_arguments = signature.bind(*args, **kwargs)
+            bound_arguments.apply_defaults()
+            arguments = bound_arguments.arguments
+
+            missing_keys = []
+            for param_name, env_var_name in param_env_list:
+                if not isinstance(env_var_name, str):
+                    raise TypeError(
+                        f"Environment variable name must be a string, got"
+                        f" {type(env_var_name)}"
+                    )
+
+                value = None
+                if (
+                    param_name
+                ):  # If param_name is provided, check function argument first
+                    if not isinstance(param_name, str):
+                        raise TypeError(
+                            f"Parameter name must be a string, "
+                            f"got {type(param_name)}"
+                        )
+                    value = arguments.get(param_name)
+                    # If we found a valid value in arguments, continue to next
+                    # item
+                    if value:
+                        continue
+
+                # Check environment variable if no valid value found yet
+                value = os.environ.get(env_var_name)
+                if not value or value.strip() == "":
+                    missing_keys.append(env_var_name)
+
+            if missing_keys:
                 raise ValueError(
-                    f"Missing API keys: {', '.join(missing_environment_keys)}"
+                    "Missing or empty required API keys in "
+                    f"environment variables: {', '.join(missing_keys)}"
                 )
             return func(*args, **kwargs)
 
@@ -609,6 +649,51 @@ def retry_request(
                 raise
 
 
+def download_github_subdirectory(
+    repo: str, subdir: str, data_dir: Path, branch="main"
+):
+    r"""Download subdirectory of the Github repo of
+    the benchmark.
+
+    This function downloads all files and subdirectories from a
+    specified subdirectory of a GitHub repository and
+    saves them to a local directory.
+
+    Args:
+        repo (str): The name of the GitHub repository
+                in the format "owner/repo".
+        subdir (str): The path to the subdirectory
+            within the repository to download.
+        data_dir (Path): The local directory where
+            the files will be saved.
+        branch (str, optional): The branch of the repository to use.
+            Defaults to "main".
+    """
+    from tqdm import tqdm
+
+    api_url = (
+        f"https://api.github.com/repos/{repo}/contents/{subdir}?ref={branch}"
+    )
+    headers = {"Accept": "application/vnd.github.v3+json"}
+    response = requests.get(api_url, headers=headers)
+    response.raise_for_status()
+    files = response.json()
+    os.makedirs(data_dir, exist_ok=True)
+
+    for file in tqdm(files, desc="Downloading"):
+        file_path = data_dir / file["name"]
+
+        if file["type"] == "file":
+            file_url = file["download_url"]
+            file_response = requests.get(file_url)
+            with open(file_path, "wb") as f:
+                f.write(file_response.content)
+        elif file["type"] == "dir":
+            download_github_subdirectory(
+                repo, f'{subdir}/{file["name"]}', file_path, branch
+            )
+
+
 def generate_prompt_for_structured_output(
     response_format: Optional[Type[BaseModel]],
     user_message: str,

{camel_ai-0.2.15a0.dist-info → camel_ai-0.2.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: camel-ai
-Version: 0.2.15a0
+Version: 0.2.16
 Summary: Communicative Agents for AI Society Study
 Home-page: https://www.camel-ai.org/
 License: Apache-2.0
@@ -40,9 +40,10 @@ Requires-Dist: botocore (>=1.35.3,<2.0.0) ; extra == "object-storages" or extra
 Requires-Dist: cohere (>=5.11.0,<6.0.0) ; extra == "rag" or extra == "model-platforms" or extra == "retrievers" or extra == "all" or extra == "all"
 Requires-Dist: colorama (>=0,<1)
 Requires-Dist: curl_cffi (==0.6.2)
+Requires-Dist: dappier (>=0.3.3,<0.4.0) ; extra == "tools" or extra == "all"
 Requires-Dist: datacommons (>=1.4.3,<2.0.0) ; extra == "tools" or extra == "all"
 Requires-Dist: datacommons_pandas (>=0.0.3,<0.0.4) ; extra == "tools" or extra == "all"
-Requires-Dist: datasets (>=2,<3) ; extra == "huggingface-agent" or extra == "all"
+Requires-Dist: datasets (>=3,<4) ; extra == "huggingface-agent" or extra == "all"
 Requires-Dist: diffusers (>=0,<1) ; extra == "huggingface-agent" or extra == "all"
 Requires-Dist: discord.py (>=2.3.2,<3.0.0) ; extra == "tools" or extra == "all"
 Requires-Dist: docker (>=7.1.0,<8.0.0) ; extra == "tools" or extra == "runtime" or extra == "all"
@@ -62,6 +63,7 @@ Requires-Dist: imageio[pyav] (>=2.34.2,<3.0.0) ; extra == "tools" or extra == "a
 Requires-Dist: ipykernel (>=6.0.0,<7.0.0) ; extra == "tools" or extra == "all"
 Requires-Dist: jsonschema (>=4,<5)
 Requires-Dist: jupyter_client (>=8.6.2,<9.0.0) ; extra == "tools" or extra == "all"
+Requires-Dist: linkup-sdk (>=0.2.1,<0.3.0) ; extra == "search-tools" or extra == "tools" or extra == "all"
 Requires-Dist: litellm (>=1.38.1,<2.0.0) ; extra == "model-platforms" or extra == "all"
 Requires-Dist: mistralai (>=1.1.0,<2.0.0) ; extra == "model-platforms" or extra == "all"
 Requires-Dist: mock (>=5,<6) ; extra == "test"
@@ -72,8 +74,10 @@ Requires-Dist: notion-client (>=2.2.1,<3.0.0) ; extra == "tools" or extra == "al
 Requires-Dist: numpy (>=1,<2)
 Requires-Dist: openai (>=1.58.1,<2.0.0)
 Requires-Dist: openapi-spec-validator (>=0.7.1,<0.8.0) ; extra == "tools" or extra == "all"
+Requires-Dist: openbb (>=4.3.5,<5.0.0) ; extra == "tools" or extra == "all"
 Requires-Dist: opencv-python (>=4,<5) ; extra == "huggingface-agent" or extra == "all"
 Requires-Dist: outlines (>=0.1.7,<0.2.0) ; extra == "tools" or extra == "all"
+Requires-Dist: pandas (>=2.2.3,<3.0.0) ; extra == "tools" or extra == "all"
 Requires-Dist: pandoc
 Requires-Dist: pathlib (>=1.0.1,<2.0.0)
 Requires-Dist: pdfplumber (>=0.11.0,<0.12.0) ; extra == "tools" or extra == "all"
@@ -95,6 +99,7 @@ Requires-Dist: rank-bm25 (>=0.2.2,<0.3.0) ; extra == "rag" or extra == "retrieve
 Requires-Dist: redis (>=5.0.6,<6.0.0) ; extra == "kv-stroages" or extra == "all"
 Requires-Dist: reka-api (>=3.0.8,<4.0.0) ; extra == "model-platforms" or extra == "all"
 Requires-Dist: requests_oauthlib (>=1.3.1,<2.0.0) ; extra == "tools" or extra == "all"
+Requires-Dist: rouge (>=1.0.1,<2.0.0) ; extra == "tools" or extra == "all"
 Requires-Dist: scholarly[tor] (==1.7.11) ; extra == "tools" or extra == "all"
 Requires-Dist: sentence-transformers (>=3.0.1,<4.0.0) ; extra == "rag" or extra == "encoders" or extra == "all"
 Requires-Dist: sentencepiece (>=0,<1) ; extra == "huggingface-agent" or extra == "all"
@@ -109,7 +114,9 @@ Requires-Dist: tiktoken (>=0.7.0,<0.8.0)
 Requires-Dist: torch (==2.2.1) ; (platform_system == "Darwin" and platform_machine != "arm64") and (extra == "huggingface-agent" or extra == "all")
 Requires-Dist: torch (>=2,<3) ; (platform_system != "Darwin" or platform_machine == "arm64") and (extra == "huggingface-agent" or extra == "all")
 Requires-Dist: transformers (>=4,<5) ; extra == "huggingface-agent" or extra == "all"
-Requires-Dist: unstructured[all-docs] (==0.16.11) ; extra == "rag" or extra == "tools" or extra == "all" or extra == "all"
+Requires-Dist: tree-sitter (>=0.23.2,<0.24.0) ; extra == "tools" or extra == "all"
+Requires-Dist: tree-sitter-python (>=0.23.6,<0.24.0) ; extra == "tools" or extra == "all"
+Requires-Dist: unstructured[all-docs] (==0.16.11) ; extra == "rag" or extra == "tools" or extra == "all"
 Requires-Dist: wikipedia (>=1,<2) ; extra == "search-tools" or extra == "tools" or extra == "all"
 Requires-Dist: wolframalpha (>=5.0.0,<6.0.0) ; extra == "search-tools" or extra == "tools" or extra == "all"
 Requires-Dist: yt-dlp (>=2024.11.4,<2025.0.0) ; extra == "tools" or extra == "all"
@@ -263,7 +270,7 @@ conda create --name camel python=3.10
 conda activate camel
 
 # Clone github repo
-git clone -b v0.2.15a0 https://github.com/camel-ai/camel.git
+git clone -b v0.2.16 https://github.com/camel-ai/camel.git
 
 # Change directory into project directory
 cd camel
@@ -444,6 +451,9 @@ Practical guides and tutorials for implementing specific functionalities in CAME
 | **[Customer Service Discord Bot with Agentic RAG](https://docs.camel-ai.org/cookbooks/customer_service_Discord_bot_with_agentic_RAG.html)** |  Learn how to build a robust customer service bot for Discord using Agentic RAG. |
 | **[Create AI Agents that work with your PDFs using Chunkr & Mistral AI](https://docs.camel-ai.org/cookbooks/agent_with_chunkr_for_pdf_parsing.html)** | Learn how to create AI agents that work with your PDFs using Chunkr and Mistral AI. |
 | **[Data Gen with Real Function Calls and Hermes Format](https://docs.camel-ai.org/cookbooks/data_gen_with_real_function_calls_and_hermes_format.html)** |  Explore how to generate data with real function calls and the Hermes format. |
+| **[CoT Data Generation and Upload Data to Huggingface](https://docs.camel-ai.org/cookbooks/cot_data_gen_upload_to_huggingface.html)** | Uncover how to generate CoT data with CAMEL and seamlessly upload it to Huggingface. |
+| **[CoT Data Generation and SFT Qwen with Unsolth, Uploading Data and Model to Hugging Face](https://docs.camel-ai.org/cookbooks/cot_data_gen_sft_qwen_unsolth_upload_huggingface.html)** | Discover how to generate CoT data using CAMEL and SFT Qwen with Unsolth, and seamlessly upload your data and model to Huggingface. |
+| **[Customer Service Discord Bot with Agentic RAG supports local model deployment](https://docs.camel-ai.org/cookbooks/customer_service_Discord_bot_using_local_model_with_agentic_RAG.html)** | Learn how to build a robust customer service bot for Discord using Agentic RAG which supports local deployment. |
 
 ## Utilize Various LLMs as Backends
 
@@ -473,6 +483,8 @@ We implemented amazing research ideas from other works for you to build, compare
 
 - `PersonaHub` from *Tao Ge et al.*: [Scaling Synthetic Data Creation with 1,000,000,000 Personas](https://arxiv.org/pdf/2406.20094). [[Example](https://github.com/camel-ai/camel/blob/master/examples/personas/personas_generation.py)]
 
+- `Self-Instruct` from *Yizhong Wang et al.*: [SELF-INSTRUCT: Aligning Language Models with Self-Generated Instructions](https://arxiv.org/pdf/2212.10560). [[Example](https://github.com/camel-ai/camel/blob/master/examples/datagen/self_instruct/self_instruct.py)]
+
 ## Other Research Works Based on Camel
 - [Agent Trust](http://agent-trust.camel-ai.org/): Can Large Language Model Agents Simulate Human Trust Behavior?