camel-ai 0.1.1__py3-none-any.whl → 0.1.4__py3-none-any.whl

camel/utils/commons.py

@@ -11,26 +11,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
-import inspect
+import importlib
 import os
+import platform
 import re
 import socket
 import time
 import zipfile
 from functools import wraps
-from typing import (
-    Any,
-    Callable,
-    Dict,
-    List,
-    Optional,
-    Set,
-    Tuple,
-    TypeVar,
-    cast,
-)
+from typing import Any, Callable, List, Optional, Set, TypeVar, cast
 from urllib.parse import urlparse
 
+import pydantic
 import requests
 
 from camel.types import TaskType
@@ -38,9 +30,8 @@ from camel.types import TaskType
 F = TypeVar('F', bound=Callable[..., Any])
 
 
-def openai_api_key_required(func: F) -> F:
-    r"""Decorator that checks if the OpenAI API key is available in the
-    environment variables.
+def api_key_required(func: F) -> F:
+    r"""Decorator that checks if the API key is available either as an environment variable or passed directly.
 
     Args:
         func (callable): The function to be wrapped.
@@ -49,16 +40,22 @@ def openai_api_key_required(func: F) -> F:
         callable: The decorated function.
 
     Raises:
-        ValueError: If the OpenAI API key is not found in the environment
-            variables.
+        ValueError: If the API key is not found, either as an environment
+            variable or directly passed.
     """
 
     @wraps(func)
     def wrapper(self, *args, **kwargs):
-        if 'OPENAI_API_KEY' in os.environ:
+        if self.model_type.is_openai:
+            if not self._api_key and 'OPENAI_API_KEY' not in os.environ:
+                raise ValueError('OpenAI API key not found.')
+            return func(self, *args, **kwargs)
+        elif self.model_type.is_anthropic:
+            if 'ANTHROPIC_API_KEY' not in os.environ:
+                raise ValueError('Anthropic API key not found.')
             return func(self, *args, **kwargs)
         else:
-            raise ValueError('OpenAI API key not found.')
+            raise ValueError('Unsupported model type.')
 
     return cast(F, wrapper)
 
@@ -116,12 +113,26 @@ def get_first_int(string: str) -> Optional[int]:
 
 
 def download_tasks(task: TaskType, folder_path: str) -> None:
+    r"""Downloads task-related files from a specified URL and extracts them.
+
+    This function downloads a zip file containing tasks based on the specified
+    `task` type from a predefined URL, saves it to `folder_path`, and then
+    extracts the contents of the zip file into the same folder. After
+    extraction, the zip file is deleted.
+
+    Args:
+        task (TaskType): An enum representing the type of task to download.
+        folder_path (str): The path of the folder where the zip file will be
+                           downloaded and extracted.
+    """
     # Define the path to save the zip file
     zip_file_path = os.path.join(folder_path, "tasks.zip")
 
     # Download the zip file from the Google Drive link
-    response = requests.get("https://huggingface.co/datasets/camel-ai/"
-                            f"metadata/resolve/main/{task.value}_tasks.zip")
+    response = requests.get(
+        "https://huggingface.co/datasets/camel-ai/"
+        f"metadata/resolve/main/{task.value}_tasks.zip"
+    )
 
     # Save the zip file
     with open(zip_file_path, "wb") as f:
@@ -134,70 +145,6 @@ def download_tasks(task: TaskType, folder_path: str) -> None:
     os.remove(zip_file_path)
 
 
-def parse_doc(func: Callable) -> Dict[str, Any]:
-    r"""Parse the docstrings of a function to extract the function name,
-    description and parameters.
-
-    Args:
-        func (Callable): The function to be parsed.
-    Returns:
-        Dict[str, Any]: A dictionary with the function's name,
-            description, and parameters.
-    """
-
-    doc = inspect.getdoc(func)
-    if not doc:
-        raise ValueError(
-            f"Invalid function {func.__name__}: no docstring provided.")
-
-    properties = {}
-    required = []
-
-    parts = re.split(r'\n\s*\n', doc)
-    func_desc = parts[0].strip()
-
-    args_section = next((p for p in parts if 'Args:' in p), None)
-    if args_section:
-        args_descs: List[Tuple[str, str, str, ]] = re.findall(
-            r'(\w+)\s*\((\w+)\):\s*(.*)', args_section)
-        properties = {
-            name.strip(): {
-                'type': type,
-                'description': desc
-            }
-            for name, type, desc in args_descs
-        }
-        for name in properties:
-            required.append(name)
-
-    # Parameters from the function signature
-    sign_params = list(inspect.signature(func).parameters.keys())
-    if len(sign_params) != len(required):
-        raise ValueError(
-            f"Number of parameters in function signature ({len(sign_params)})"
-            f" does not match that in docstring ({len(required)}).")
-
-    for param in sign_params:
-        if param not in required:
-            raise ValueError(f"Parameter '{param}' in function signature"
-                             " is missing in the docstring.")
-
-    parameters = {
-        "type": "object",
-        "properties": properties,
-        "required": required,
-    }
-
-    # Construct the function dictionary
-    function_dict = {
-        "name": func.__name__,
-        "description": func_desc,
-        "parameters": parameters,
-    }
-
-    return function_dict
-
-
 def get_task_list(task_response: str) -> List[str]:
     r"""Parse the response of the Agent and return task list.
 
@@ -241,3 +188,141 @@ def check_server_running(server_url: str) -> bool:
 
     # if the port is open, the result should be 0.
     return result == 0
+
+
+def dependencies_required(*required_modules: str) -> Callable[[F], F]:
+    r"""A decorator to ensure that specified Python modules
+    are available before a function executes.
+
+    Args:
+        required_modules (str): The required modules to be checked for
+            availability.
+
+    Returns:
+        Callable[[F], F]: The original function with the added check for
+            required module dependencies.
+
+    Raises:
+        ImportError: If any of the required modules are not available.
+
+    Example:
+        ::
+
+            @dependencies_required('numpy', 'pandas')
+            def data_processing_function():
+                # Function implementation...
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            missing_modules = [
+                m for m in required_modules if not is_module_available(m)
+            ]
+            if missing_modules:
+                raise ImportError(
+                    f"Missing required modules: {', '.join(missing_modules)}"
+                )
+            return func(*args, **kwargs)
+
+        return cast(F, wrapper)
+
+    return decorator
+
+
+def is_module_available(module_name: str) -> bool:
+    r"""Check if a module is available for import.
+
+    Args:
+        module_name (str): The name of the module to check for availability.
+
+    Returns:
+        bool: True if the module can be imported, False otherwise.
+    """
+    try:
+        importlib.import_module(module_name)
+        return True
+    except ImportError:
+        return False
+
+
+def api_keys_required(*required_keys: str) -> Callable[[F], F]:
+    r"""A decorator to check if the required API keys are
+    present in the environment variables.
+
+    Args:
+        required_keys (str): The required API keys to be checked.
+
+    Returns:
+        Callable[[F], F]: The original function with the added check
+            for required API keys.
+
+    Raises:
+        ValueError: If any of the required API keys are missing in the
+            environment variables.
+
+    Example:
+        ::
+
+            @api_keys_required('API_KEY_1', 'API_KEY_2')
+            def some_api_function():
+                # Function implementation...
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            missing_keys = [k for k in required_keys if k not in os.environ]
+            if missing_keys:
+                raise ValueError(f"Missing API keys: {', '.join(missing_keys)}")
+            return func(*args, **kwargs)
+
+        return cast(F, wrapper)
+
+    return decorator
+
+
+def get_system_information():
+    r"""Gathers information about the operating system.
+
+    Returns:
+        dict: A dictionary containing various pieces of OS information.
+    """
+    sys_info = {
+        "OS Name": os.name,
+        "System": platform.system(),
+        "Release": platform.release(),
+        "Version": platform.version(),
+        "Machine": platform.machine(),
+        "Processor": platform.processor(),
+        "Platform": platform.platform(),
+    }
+
+    return sys_info
+
+
+def to_pascal(snake: str) -> str:
+    """Convert a snake_case string to PascalCase.
+
+    Args:
+        snake (str): The snake_case string to be converted.
+
+    Returns:
+        str: The converted PascalCase string.
+    """
+    # Check if the string is already in PascalCase
+    if re.match(r'^[A-Z][a-zA-Z0-9]*([A-Z][a-zA-Z0-9]*)*$', snake):
+        return snake
+    # Remove leading and trailing underscores
+    snake = snake.strip('_')
+    # Replace multiple underscores with a single one
+    snake = re.sub('_+', '_', snake)
+    # Convert to PascalCase
+    return re.sub(
+        '_([0-9A-Za-z])',
+        lambda m: m.group(1).upper(),
+        snake.title(),
+    )
+
+
+PYDANTIC_V2 = pydantic.VERSION.startswith("2.")

camel/utils/token_counting.py

@@ -11,11 +11,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
+
+from __future__ import annotations
+
+import base64
 from abc import ABC, abstractmethod
-from typing import List
+from io import BytesIO
+from math import ceil
+from typing import TYPE_CHECKING, List, Optional
+
+from anthropic import Anthropic
+from PIL import Image
 
-from camel.messages import OpenAIMessage
-from camel.types import ModelType
+from camel.types import ModelType, OpenAIImageDetailType, OpenAIImageType
+
+if TYPE_CHECKING:
+    from camel.messages import OpenAIMessage
+
+LOW_DETAIL_TOKENS = 85
+FIT_SQUARE_PIXELS = 2048
+SHORTEST_SIDE_PIXELS = 768
+SQUARE_PIXELS = 512
+SQUARE_TOKENS = 170
+EXTRA_TOKENS = 85
 
 
 def messages_to_prompt(messages: List[OpenAIMessage], model: ModelType) -> str:
@@ -45,8 +63,10 @@ def messages_to_prompt(messages: List[OpenAIMessage], model: ModelType) -> str:
             content = msg["content"]
             if content:
                 if not isinstance(content, str):
-                    raise ValueError("Currently multimodal context is not "
-                                     "supported by the token counter.")
+                    raise ValueError(
+                        "Currently multimodal context is not "
+                        "supported by the token counter."
+                    )
                 if i == 0:
                     ret += system_prompt + content
                 else:
@@ -64,8 +84,10 @@ def messages_to_prompt(messages: List[OpenAIMessage], model: ModelType) -> str:
             role = role_map[msg["role"]]
             content = msg["content"]
             if not isinstance(content, str):
-                raise ValueError("Currently multimodal context is not "
-                                 "supported by the token counter.")
+                raise ValueError(
+                    "Currently multimodal context is not "
+                    "supported by the token counter."
+                )
             if content:
                 ret += role + ": " + content + seps[i % 2]
             else:
@@ -85,6 +107,7 @@ def get_model_encoding(value_for_tiktoken: str):
         tiktoken.Encoding: Model encoding.
     """
     import tiktoken
+
     try:
         encoding = tiktoken.encoding_for_model(value_for_tiktoken)
     except KeyError:
@@ -111,7 +134,6 @@ class BaseTokenCounter(ABC):
 
 
 class OpenSourceTokenCounter(BaseTokenCounter):
-
     def __init__(self, model_type: ModelType, model_path: str):
         r"""Constructor for the token counter for open-source models.
 
@@ -126,6 +148,7 @@ class OpenSourceTokenCounter(BaseTokenCounter):
         # If a fast tokenizer is not available for a given model,
         # a normal Python-based tokenizer is returned instead.
         from transformers import AutoTokenizer
+
         try:
             tokenizer = AutoTokenizer.from_pretrained(
                 model_path,
@@ -136,10 +159,11 @@ class OpenSourceTokenCounter(BaseTokenCounter):
                 model_path,
                 use_fast=False,
             )
-        except:
+        except Exception:
             raise ValueError(
                 f"Invalid `model_path` ({model_path}) is provided. "
-                "Tokenizer loading failed.")
+                "Tokenizer loading failed."
+            )
 
         self.tokenizer = tokenizer
         self.model_type = model_type
@@ -162,13 +186,11 @@ class OpenSourceTokenCounter(BaseTokenCounter):
 
 
 class OpenAITokenCounter(BaseTokenCounter):
-
     def __init__(self, model: ModelType):
         r"""Constructor for the token counter for OpenAI models.
 
         Args:
-            model_type (ModelType): Model type for which tokens will be
-                counted.
+            model (ModelType): Model type for which tokens will be counted.
         """
         self.model: str = model.value_for_tiktoken
 
@@ -192,7 +214,8 @@ class OpenAITokenCounter(BaseTokenCounter):
                 "for information on how messages are converted to tokens. "
                 "See https://platform.openai.com/docs/models/gpt-4"
                 "or https://platform.openai.com/docs/models/gpt-3-5"
-                "for information about openai chat models.")
+                "for information about openai chat models."
+            )
 
         self.encoding = get_model_encoding(self.model)
 
@@ -211,10 +234,107 @@ class OpenAITokenCounter(BaseTokenCounter):
         for message in messages:
             num_tokens += self.tokens_per_message
             for key, value in message.items():
-                num_tokens += len(self.encoding.encode(str(value)))
+                if not isinstance(value, list):
+                    num_tokens += len(self.encoding.encode(str(value)))
+                else:
+                    for item in value:
+                        if item["type"] == "text":
+                            num_tokens += len(
+                                self.encoding.encode(str(item["text"]))
+                            )
+                        elif item["type"] == "image_url":
+                            image_str: str = item["image_url"]["url"]
+                            detail = item["image_url"]["detail"]
+                            image_prefix_format = "data:image/{};base64,"
+                            image_prefix: Optional[str] = None
+                            for image_type in list(OpenAIImageType):
+                                # Find the correct image format
+                                image_prefix = image_prefix_format.format(
+                                    image_type.value
+                                )
+                                if image_prefix in image_str:
+                                    break
+                            assert isinstance(image_prefix, str)
+                            encoded_image = image_str.split(image_prefix)[1]
+                            image_bytes = BytesIO(
+                                base64.b64decode(encoded_image)
+                            )
+                            image = Image.open(image_bytes)
+                            num_tokens += count_tokens_from_image(
+                                image, OpenAIImageDetailType(detail)
+                            )
                 if key == "name":
                     num_tokens += self.tokens_per_name
 
         # every reply is primed with <|start|>assistant<|message|>
         num_tokens += 3
         return num_tokens
+
+
+class AnthropicTokenCounter(BaseTokenCounter):
+    def __init__(self, model_type: ModelType):
+        r"""Constructor for the token counter for Anthropic models.
+
+        Args:
+            model_type (ModelType): Model type for which tokens will be
+                counted.
+        """
+
+        self.model_type = model_type
+        self.client = Anthropic()
+        self.tokenizer = self.client.get_tokenizer()
+
+    def count_tokens_from_messages(self, messages: List[OpenAIMessage]) -> int:
+        r"""Count number of tokens in the provided message list using
+        loaded tokenizer specific for this type of model.
+
+        Args:
+            messages (List[OpenAIMessage]): Message list with the chat history
+                in OpenAI API format.
+
+        Returns:
+            int: Number of tokens in the messages.
+        """
+        prompt = messages_to_prompt(messages, self.model_type)
+
+        return self.client.count_tokens(prompt)
+
+
+def count_tokens_from_image(
+    image: Image.Image, detail: OpenAIImageDetailType
+) -> int:
+    r"""Count image tokens for OpenAI vision model. An :obj:`"auto"`
+    resolution model will be treated as :obj:`"high"`. All images with
+    :obj:`"low"` detail cost 85 tokens each. Images with :obj:`"high"` detail
+    are first scaled to fit within a 2048 x 2048 square, maintaining their
+    aspect ratio. Then, they are scaled such that the shortest side of the
+    image is 768px long. Finally, we count how many 512px squares the image
+    consists of. Each of those squares costs 170 tokens. Another 85 tokens are
+    always added to the final total. For more details please refer to `OpenAI
+    vision docs <https://platform.openai.com/docs/guides/vision>`_
+
+    Args:
+        image (PIL.Image.Image): Image to count number of tokens.
+        detail (OpenAIImageDetailType): Image detail type to count
+            number of tokens.
+
+    Returns:
+        int: Number of tokens for the image given a detail type.
+    """
+    if detail == OpenAIImageDetailType.LOW:
+        return LOW_DETAIL_TOKENS
+
+    width, height = image.size
+    if width > FIT_SQUARE_PIXELS or height > FIT_SQUARE_PIXELS:
+        scaling_factor = max(width, height) / FIT_SQUARE_PIXELS
+        width = int(width / scaling_factor)
+        height = int(height / scaling_factor)
+
+    scaling_factor = min(width, height) / SHORTEST_SIDE_PIXELS
+    scaled_width = int(width / scaling_factor)
+    scaled_height = int(height / scaling_factor)
+
+    h = ceil(scaled_height / SQUARE_PIXELS)
+    w = ceil(scaled_width / SQUARE_PIXELS)
+    total = EXTRA_TOKENS + SQUARE_TOKENS * h * w
+    return total