camel-ai 0.2.35__py3-none-any.whl → 0.2.37__py3-none-any.whl

camel/models/openrouter_model.py

@@ -0,0 +1,204 @@
+# ========= 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 Any, Dict, List, Optional, Type, Union
+
+from openai import AsyncOpenAI, AsyncStream, OpenAI, Stream
+from pydantic import BaseModel
+
+from camel.configs import OPENROUTER_API_PARAMS, OpenRouterConfig
+from camel.messages import OpenAIMessage
+from camel.models import BaseModelBackend
+from camel.models._utils import try_modify_message_with_format
+from camel.types import (
+    ChatCompletion,
+    ChatCompletionChunk,
+    ModelType,
+)
+from camel.utils import (
+    BaseTokenCounter,
+    OpenAITokenCounter,
+    api_keys_required,
+)
+
+
+class OpenRouterModel(BaseModelBackend):
+    r"""LLM API served by OpenRouter in a unified BaseModelBackend interface.
+
+    Args:
+        model_type (Union[ModelType, str]): Model for which a backend is
+            created.
+        model_config_dict (Optional[Dict[str, Any]], optional): A dictionary
+            that will be fed into:obj:`openai.ChatCompletion.create()`.
+            If:obj:`None`, :obj:`GroqConfig().as_dict()` will be used.
+            (default: :obj:`None`)
+        api_key (Optional[str], optional): The API key for authenticating
+            with the OpenRouter service. (default: :obj:`None`).
+        url (Optional[str], optional): The url to the OpenRouter service.
+            (default: :obj:`None`)
+        token_counter (Optional[BaseTokenCounter], optional): Token counter to
+            use for the model. If not provided, :obj:`OpenAITokenCounter(
+            ModelType.GPT_4O_MINI)` will be used.
+            (default: :obj:`None`)
+    """
+
+    @api_keys_required([("api_key", "OPENROUTER_API_KEY")])
+    def __init__(
+        self,
+        model_type: Union[ModelType, str],
+        model_config_dict: Optional[Dict[str, Any]] = None,
+        api_key: Optional[str] = None,
+        url: Optional[str] = None,
+        token_counter: Optional[BaseTokenCounter] = None,
+    ) -> None:
+        if model_config_dict is None:
+            model_config_dict = OpenRouterConfig().as_dict()
+        api_key = api_key or os.environ.get("OPENROUTER_API_KEY")
+        url = url or os.environ.get(
+            "OPENROUTER_API_BASE_URL", "https://openrouter.ai/api/v1"
+        )
+        super().__init__(
+            model_type, model_config_dict, api_key, url, token_counter
+        )
+        self._client = OpenAI(
+            timeout=180,
+            max_retries=3,
+            api_key=self._api_key,
+            base_url=self._url,
+        )
+        self._async_client = AsyncOpenAI(
+            timeout=180,
+            max_retries=3,
+            api_key=self._api_key,
+            base_url=self._url,
+        )
+
+    @property
+    def token_counter(self) -> BaseTokenCounter:
+        r"""Initialize the token counter for the model backend.
+
+        Returns:
+            BaseTokenCounter: The token counter following the model's
+                tokenization style.
+        """
+        if not self._token_counter:
+            self._token_counter = OpenAITokenCounter(ModelType.GPT_4O_MINI)
+        return self._token_counter
+
+    def _prepare_request(
+        self,
+        messages: List[OpenAIMessage],
+        response_format: Optional[Type[BaseModel]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> Dict[str, Any]:
+        request_config = self.model_config_dict.copy()
+        if tools:
+            request_config["tools"] = tools
+        elif response_format:
+            try_modify_message_with_format(messages[-1], response_format)
+            request_config["response_format"] = {"type": "json_object"}
+
+        return request_config
+
+    def _run(
+        self,
+        messages: List[OpenAIMessage],
+        response_format: Optional[type[BaseModel]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> Union[ChatCompletion, Stream[ChatCompletionChunk]]:
+        r"""Runs inference of OpenAI chat completion.
+
+        Args:
+            messages (List[OpenAIMessage]): Message list with the chat history
+                in OpenAI API format.
+            response_format (Optional[Type[BaseModel]]): The format of the
+                response.
+            tools (Optional[List[Dict[str, Any]]]): The schema of the tools to
+                use for the request.
+
+        Returns:
+            Union[ChatCompletion, Stream[ChatCompletionChunk]]:
+                `ChatCompletion` in the non-stream mode, or
+                `Stream[ChatCompletionChunk]` in the stream mode.
+        """
+        request_config = self._prepare_request(
+            messages, response_format, tools
+        )
+
+        response = self._client.chat.completions.create(
+            messages=messages,
+            model=self.model_type,
+            **request_config,
+        )
+
+        return response
+
+    async def _arun(
+        self,
+        messages: List[OpenAIMessage],
+        response_format: Optional[type[BaseModel]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> Union[ChatCompletion, AsyncStream[ChatCompletionChunk]]:
+        r"""Runs inference of OpenRouter chat completion asynchronously.
+
+        Args:
+            messages (List[OpenAIMessage]): Message list with the chat history
+                in OpenAI API format.
+            response_format (Optional[Type[BaseModel]]): The format of the
+                response.
+            tools (Optional[List[Dict[str, Any]]]): The schema of the tools to
+                use for the request.
+
+        Returns:
+            Union[ChatCompletion, AsyncStream[ChatCompletionChunk]]:
+                `ChatCompletion` in the non-stream mode, or
+                `AsyncStream[ChatCompletionChunk]` in the stream mode.
+        """
+        request_config = self._prepare_request(
+            messages, response_format, tools
+        )
+
+        response = await self._async_client.chat.completions.create(
+            messages=messages,
+            model=self.model_type,
+            **request_config,
+        )
+
+        return response
+
+    def check_model_config(self):
+        r"""Check whether the model configuration contains any unexpected
+        arguments to OpenRouter API. But OpenRouter API does not have any
+        additional arguments to check.
+
+        Raises:
+            ValueError: If the model configuration dictionary contains any
+                unexpected arguments to OpenRouter API.
+        """
+        for param in self.model_config_dict:
+            if param not in OPENROUTER_API_PARAMS:
+                raise ValueError(
+                    f"Unexpected argument `{param}` is "
+                    "input into OpenRouter model backend."
+                )
+
+    @property
+    def stream(self) -> bool:
+        r"""Returns whether the model is in stream mode, which sends partial
+        results each time.
+
+        Returns:
+            bool: Whether the model is in stream mode.
+        """
+        return self.model_config_dict.get("stream", False)

camel/storages/__init__.py

@@ -18,6 +18,7 @@ from .graph_storages.neo4j_graph import Neo4jGraph
 from .key_value_storages.base import BaseKeyValueStorage
 from .key_value_storages.in_memory import InMemoryKeyValueStorage
 from .key_value_storages.json import JsonStorage
+from .key_value_storages.mem0_cloud import Mem0Storage
 from .key_value_storages.redis import RedisStorage
 from .vectordb_storages.base import (
     BaseVectorStorage,
@@ -42,4 +43,5 @@ __all__ = [
     'BaseGraphStorage',
     'Neo4jGraph',
     'NebulaGraph',
+    'Mem0Storage',
 ]

camel/storages/key_value_storages/__init__.py

@@ -15,6 +15,7 @@
 from .base import BaseKeyValueStorage
 from .in_memory import InMemoryKeyValueStorage
 from .json import CamelJSONEncoder, JsonStorage
+from .mem0_cloud import Mem0Storage
 from .redis import RedisStorage
 
 __all__ = [
@@ -23,4 +24,5 @@ __all__ = [
     'JsonStorage',
     'RedisStorage',
     'CamelJSONEncoder',
+    'Mem0Storage',
 ]

camel/storages/key_value_storages/mem0_cloud.py

@@ -0,0 +1,224 @@
+# ========= 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 logging
+import os
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from camel.memories.records import MemoryRecord
+from camel.messages import BaseMessage
+from camel.storages.key_value_storages import BaseKeyValueStorage
+from camel.types import OpenAIBackendRole, RoleType
+
+logger = logging.getLogger(__name__)
+
+
+class Mem0Storage(BaseKeyValueStorage):
+    r"""A concrete implementation of the :obj:`BaseKeyValueStorage` using Mem0
+    as the backend. This storage system uses Mem0's text capabilities to store,
+    search, and manage text with context.
+
+    Args:
+        agent_id (str): Default agent ID to associate memories with.
+        api_key (str, optional): The API key for authentication. If not
+            provided, will try to get from environment variable MEM0_API_KEY
+            (default: :obj:`None`).
+        user_id (str, optional): Default user ID to associate memories with
+            (default: :obj:`None`).
+        metadata (Dict[str, Any], optional): Default metadata to include with
+            all memories (default: :obj:`None`).
+
+    References:
+        https://docs.mem0.ai
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        api_key: Optional[str] = None,
+        user_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        try:
+            from mem0 import MemoryClient
+        except ImportError as exc:
+            logger.error(
+                "Please install `mem0` first. You can install it by "
+                "running `pip install mem0ai`."
+            )
+            raise exc
+
+        self.api_key = api_key or os.getenv("MEM0_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "API key must be provided either through constructor "
+                "or MEM0_API_KEY environment variable."
+            )
+
+        self.client = MemoryClient(api_key=self.api_key)
+        self.agent_id = agent_id
+        self.user_id = user_id
+        self.metadata = metadata or {}
+
+    def _prepare_options(
+        self,
+        agent_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        r"""Helper method to prepare options for Mem0 API calls.
+
+        Args:
+            agent_id (Optional[str], optional): Agent ID to use (default:
+                :obj:`None`).
+            user_id (Optional[str], optional): User ID to use (default:
+                :obj:`None`).
+            metadata (Optional[Dict[str, Any]], optional): Additional metadata
+                to include (default: :obj:`None`).
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+            Dict[str, Any]: Prepared options dictionary for API calls.
+        """
+        options = {
+            "agent_id": agent_id or self.agent_id,
+            "user_id": user_id or self.user_id,
+            "metadata": {**self.metadata, **(metadata or {})},
+            "output_format": "v1.1",
+            **kwargs,
+        }
+        return {k: v for k, v in options.items() if v is not None}
+
+    def _prepare_filters(
+        self,
+        agent_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        r"""Helper method to prepare filters for Mem0 API calls.
+
+        Args:
+            agent_id (Optional[str], optional): Agent ID to filter by
+                (default: :obj:`None`).
+            user_id (Optional[str], optional): User ID to filter by (default:
+                :obj:`None`).
+            filters (Optional[Dict[str, Any]], optional): Additional filters
+                (default: :obj:`None`).
+
+        Returns:
+            Dict[str, Any]: Prepared filters dictionary for API calls.
+        """
+        base_filters: Dict[str, Any] = {"AND": []}
+        if filters:
+            base_filters["AND"].append(filters)
+        if agent_id or self.agent_id:
+            base_filters["AND"].append({"agent_id": agent_id or self.agent_id})
+        if user_id or self.user_id:
+            base_filters["AND"].append({"user_id": user_id or self.user_id})
+        return base_filters if base_filters["AND"] else {}
+
+    def _prepare_messages(
+        self,
+        records: List[Dict[str, Any]],
+    ) -> List[Dict[str, Any]]:
+        r"""Prepare messages from records for Mem0 API calls.
+
+        Args:
+            records (List[Dict[str, Any]]): List of record dictionaries.
+
+        Returns:
+            List[Dict[str, Any]]: List of prepared message dictionaries.
+        """
+        messages = []
+        for record in records:
+            content = record["message"]["content"]
+            role = record["role_at_backend"].value
+            messages.append({"role": role, "content": content})
+        return messages
+
+    def save(self, records: List[Dict[str, Any]]) -> None:
+        r"""Saves a batch of records to the Mem0 storage system.
+
+        Args:
+            records (List[Dict[str, Any]]): A list of dictionaries, where each
+                dictionary represents a unique record to be stored.
+        """
+        try:
+            messages = self._prepare_messages(records)
+
+            options = self._prepare_options(
+                agent_id=self.agent_id,
+                user_id=self.user_id,
+                metadata=self.metadata,
+            )
+            self.client.add(messages, **options)
+        except Exception as e:
+            logger.error(f"Error adding memory: {e}")
+            logger.error(f"Error: {e}")
+
+    def load(self) -> List[Dict[str, Any]]:
+        r"""Loads all stored records from the Mem0 storage system.
+
+        Returns:
+            List[Dict[str, Any]]: A list of dictionaries, where each dictionary
+                represents a stored record.
+        """
+        try:
+            filters = self._prepare_filters(
+                agent_id=self.agent_id,
+                user_id=self.user_id,
+            )
+            results = self.client.get_all(version="v2", **filters)
+
+            # Transform results into MemoryRecord objects
+            transformed_results = []
+            for result in results:
+                memory_record = MemoryRecord(
+                    uuid=UUID(result["id"]),
+                    message=BaseMessage(
+                        role_name="user",
+                        role_type=RoleType.USER,
+                        meta_dict={},
+                        content=result["memory"],
+                    ),
+                    role_at_backend=OpenAIBackendRole.USER,
+                    extra_info=result.get("metadata", {}),
+                    timestamp=datetime.fromisoformat(
+                        result["created_at"]
+                    ).timestamp(),
+                    agent_id=result.get("agent_id", ""),
+                )
+                transformed_results.append(memory_record.to_dict())
+
+            return transformed_results
+        except Exception as e:
+            logger.error(f"Error searching memories: {e}")
+            return []
+
+    def clear(
+        self,
+    ) -> None:
+        r"""Removes all records from the Mem0 storage system."""
+        try:
+            filters = self._prepare_filters(
+                agent_id=self.agent_id,
+                user_id=self.user_id,
+            )
+            self.client.delete_users(**filters)
+        except Exception as e:
+            logger.error(f"Error deleting memories: {e}")
+            logger.error(f"Error: {e}")

camel/storages/vectordb_storages/qdrant.py

@@ -450,9 +450,9 @@ class QdrantStorage(BaseVectorStorage):
             search_filter = Filter(must=cast(List[Condition], must_conditions))
 
         # Execute the search with optional filter
-        search_result = self._client.search(
+        search_result = self._client.query_points(
             collection_name=self.collection_name,
-            query_vector=query.query_vector,
+            query=query.query_vector,
             with_payload=True,
             with_vectors=True,
             limit=query.top_k,
@@ -467,7 +467,7 @@ class QdrantStorage(BaseVectorStorage):
                 payload=point.payload,
                 vector=point.vector,  # type: ignore[arg-type]
             )
-            for point in search_result
+            for point in search_result.points
         ]
 
         return query_results

camel/toolkits/__init__.py

@@ -60,6 +60,7 @@ from .browser_toolkit import BrowserToolkit
 from .file_write_toolkit import FileWriteToolkit
 from .terminal_toolkit import TerminalToolkit
 from .pubmed_toolkit import PubMedToolkit
+from .thinking_toolkit import ThinkingToolkit
 
 __all__ = [
     'BaseToolkit',
@@ -108,4 +109,5 @@ __all__ = [
     'FileWriteToolkit',
     'TerminalToolkit',
     'PubMedToolkit',
+    'ThinkingToolkit',
 ]

camel/toolkits/browser_toolkit.py

@@ -438,6 +438,7 @@ class BaseBrowser:
             sync_playwright,
         )
 
+        self._ensure_browser_installed()
         self.history: list = []
         self.headless = headless
         self.playwright = sync_playwright().start()
@@ -914,6 +915,48 @@ class BaseBrowser:
         markdown_content = html2text(html_content)
         return markdown_content
 
+    def _ensure_browser_installed(self) -> None:
+        r"""Ensure the browser is installed."""
+        import platform
+        import subprocess
+        import sys
+
+        try:
+            from playwright.sync_api import sync_playwright
+
+            with sync_playwright() as p:
+                browser = p.chromium.launch()
+                browser.close()
+        except Exception:
+            logger.info("Installing Chromium browser...")
+            try:
+                subprocess.run(
+                    [
+                        sys.executable,
+                        "-m",
+                        "playwright",
+                        "install",
+                        "chromium",
+                    ],
+                    check=True,
+                    capture_output=True,
+                )
+                if platform.system().lower() == "linux":
+                    subprocess.run(
+                        [
+                            sys.executable,
+                            "-m",
+                            "playwright",
+                            "install-deps",
+                            "chromium",
+                        ],
+                        check=True,
+                        capture_output=True,
+                    )
+                logger.info("Chromium browser installation completed")
+            except subprocess.CalledProcessError as e:
+                raise RuntimeError(f"Failed to install browser: {e.stderr}")
+
 
 class BrowserToolkit(BaseToolkit):
     r"""A class for browsing the web and interacting with web pages.

camel/toolkits/code_execution.py

@@ -29,6 +29,7 @@ class CodeExecutionToolkit(BaseToolkit):
 
     Args:
         sandbox (str): The environment type used to execute code.
+            (default: `subprocess`)
         verbose (bool): Whether to print the output of the code execution.
             (default: :obj:`False`)
         unsafe_mode (bool):  If `True`, the interpreter runs the code
@@ -43,7 +44,7 @@ class CodeExecutionToolkit(BaseToolkit):
         self,
         sandbox: Literal[
             "internal_python", "jupyter", "docker", "subprocess", "e2b"
-        ] = "internal_python",
+        ] = "subprocess",
         verbose: bool = False,
         unsafe_mode: bool = False,
         import_white_list: Optional[List[str]] = None,

camel/toolkits/mcp_toolkit.py

@@ -56,6 +56,8 @@ class _MCPServer(BaseToolkit):
         env (Dict[str, str]): Environment variables for the stdio mode command.
             (default: :obj:`'None'`)
         timeout (Optional[float]): Connection timeout. (default: :obj:`'None'`)
+        headers (Dict[str, str]): Headers for the HTTP request.
+            (default: :obj:`'None'`)
     """
 
     def __init__(
@@ -64,6 +66,7 @@ class _MCPServer(BaseToolkit):
         args: Optional[List[str]] = None,
         env: Optional[Dict[str, str]] = None,
         timeout: Optional[float] = None,
+        headers: Optional[Dict[str, str]] = None,
     ):
         from mcp import Tool
         from mcp.client.session import ClientSession
@@ -73,6 +76,7 @@ class _MCPServer(BaseToolkit):
         self.command_or_url = command_or_url
         self.args = args or []
         self.env = env or {}
+        self.headers = headers or {}
 
         self._mcp_tools: List[Tool] = []
         self._session: Optional['ClientSession'] = None
@@ -99,7 +103,10 @@ class _MCPServer(BaseToolkit):
                     read_stream,
                     write_stream,
                 ) = await self._exit_stack.enter_async_context(
-                    sse_client(self.command_or_url)
+                    sse_client(
+                        self.command_or_url,
+                        headers=self.headers,
+                    )
                 )
             else:
                 command = self.command_or_url
@@ -343,6 +350,27 @@ class MCPToolkit(BaseToolkit):
         Either `servers` or `config_path` must be provided. If both are
         provided, servers from both sources will be combined.
 
+        For web servers in the config file, you can specify authorization
+        headers using the "headers" field to connect to protected MCP server
+        endpoints.
+
+        Example configuration:
+
+        .. code-block:: json
+
+            {
+              "mcpWebServers": {
+                "protected-server": {
+                  "url": "https://example.com/mcp",
+                  "timeout": 30,
+                  "headers": {
+                    "Authorization": "Bearer YOUR_TOKEN",
+                    "X-API-Key": "YOUR_API_KEY"
+                  }
+                }
+              }
+            }
+
     Attributes:
         servers (List[_MCPServer]): List of _MCPServer instances being managed.
     """
@@ -442,6 +470,7 @@ class MCPToolkit(BaseToolkit):
             server = _MCPServer(
                 command_or_url=cfg["url"],
                 timeout=cfg.get("timeout", None),
+                headers=cfg.get("headers", {}),
             )
             all_servers.append(server)