camel-ai 0.2.34__py3-none-any.whl → 0.2.36__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/models/stub_model.py

@@ -44,6 +44,31 @@ class StubTokenCounter(BaseTokenCounter):
         """
         return 10
 
+    def encode(self, text: str) -> List[int]:
+        r"""Encode text into token IDs for STUB models.
+
+        Args:
+            text (str): The text to encode.
+
+        Returns:
+            List[int]: List of token IDs.
+        """
+        # For stub models, just return a list of 0s with length proportional
+        # to text length
+        return [0] * (len(text) // 4 + 1)  # Simple approximation
+
+    def decode(self, token_ids: List[int]) -> str:
+        r"""Decode token IDs back to text for STUB models.
+
+        Args:
+            token_ids (List[int]): List of token IDs to decode.
+
+        Returns:
+            str: Decoded text.
+        """
+        # For stub models, return a placeholder string
+        return "[Stub decoded text]"
+
 
 class StubModel(BaseModelBackend):
     r"""A dummy model used for unit tests."""

camel/retrievers/vector_retriever.py

@@ -27,6 +27,7 @@ from camel.storages import (
     VectorRecord,
 )
 from camel.utils import Constants
+from camel.utils.chunker import BaseChunker, UnstructuredIOChunker
 
 if TYPE_CHECKING:
     from unstructured.documents.elements import Element
@@ -78,6 +79,7 @@ class VectorRetriever(BaseRetriever):
         should_chunk: bool = True,
         extra_info: Optional[dict] = None,
         metadata_filename: Optional[str] = None,
+        chunker: Optional[BaseChunker] = None,
         **kwargs: Any,
     ) -> None:
         r"""Processes content from local file path, remote URL, string
@@ -101,6 +103,12 @@ class VectorRetriever(BaseRetriever):
                 used for storing metadata. Defaults to None.
             **kwargs (Any): Additional keyword arguments for content parsing.
         """
+        if chunker is None:
+            chunker = UnstructuredIOChunker(
+                chunk_type=chunk_type,
+                max_characters=max_characters,
+                metadata_filename=metadata_filename,
+            )
         from unstructured.documents.elements import Element
 
         if isinstance(content, Element):
@@ -140,13 +148,7 @@ class VectorRetriever(BaseRetriever):
         else:
             # Chunk the content if required
             chunks = (
-                self.uio.chunk_elements(
-                    chunk_type=chunk_type,
-                    elements=elements,
-                    max_characters=max_characters,
-                )
-                if should_chunk
-                else elements
+                chunker.chunk(content=elements) if should_chunk else (elements)
             )
 
             # Process chunks in batches and store embeddings
@@ -157,6 +159,7 @@ class VectorRetriever(BaseRetriever):
                 )
 
                 records = []
+                offset = 0
                 # Prepare the payload for each vector record, includes the
                 # content path, chunk metadata, and chunk text
                 for vector, chunk in zip(batch_vectors, batch_chunks):
@@ -178,6 +181,7 @@ class VectorRetriever(BaseRetriever):
                     chunk_metadata["metadata"].pop("orig_elements", "")
                     chunk_metadata["extra_info"] = extra_info or {}
                     chunk_text = {"text": str(chunk)}
+                    chunk_metadata["metadata"]["piece_num"] = i + offset + 1
                     combined_dict = {
                         **content_path_info,
                         **chunk_metadata,
@@ -187,6 +191,7 @@ class VectorRetriever(BaseRetriever):
                     records.append(
                         VectorRecord(vector=vector, payload=combined_dict)
                     )
+                    offset += 1
 
                 self.storage.add(records=records)
 

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

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

camel/storages/key_value_storages/json.py

@@ -26,7 +26,7 @@ from camel.types import (
 )
 
 
-class _CamelJSONEncoder(json.JSONEncoder):
+class CamelJSONEncoder(json.JSONEncoder):
     r"""A custom JSON encoder for serializing specifically enumerated types.
     Ensures enumerated types can be stored in and retrieved from JSON format.
     """
@@ -62,7 +62,7 @@ class JsonStorage(BaseKeyValueStorage):
     def _json_object_hook(self, d) -> Any:
         if "__enum__" in d:
             name, member = d["__enum__"].split(".")
-            return getattr(_CamelJSONEncoder.CAMEL_ENUMS[name], member)
+            return getattr(CamelJSONEncoder.CAMEL_ENUMS[name], member)
         else:
             return d
 
@@ -75,11 +75,7 @@ class JsonStorage(BaseKeyValueStorage):
         """
         with self.json_path.open("a") as f:
             f.writelines(
-                [
-                    json.dumps(r, cls=_CamelJSONEncoder, ensure_ascii=False)
-                    + "\n"
-                    for r in records
-                ]
+                [json.dumps(r, cls=CamelJSONEncoder) + "\n" for r in records]
             )
 
     def load(self) -> List[Dict[str, Any]]:

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

@@ -87,7 +87,11 @@ class VectorDBQueryResult(BaseModel):
     ) -> "VectorDBQueryResult":
         r"""A class method to construct a `VectorDBQueryResult` instance."""
         return cls(
-            record=VectorRecord(vector=vector, id=id, payload=payload),
+            record=VectorRecord(
+                vector=vector,
+                id=id,
+                payload=payload,
+            ),
             similarity=similarity,
         )
 

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

@@ -50,6 +50,7 @@ from .semantic_scholar_toolkit import SemanticScholarToolkit
 from .zapier_toolkit import ZapierToolkit
 from .sympy_toolkit import SymPyToolkit
 from .mineru_toolkit import MinerUToolkit
+from .memory_toolkit import MemoryToolkit
 from .audio_analysis_toolkit import AudioAnalysisToolkit
 from .excel_toolkit import ExcelToolkit
 from .video_analysis_toolkit import VideoAnalysisToolkit
@@ -60,7 +61,6 @@ from .file_write_toolkit import FileWriteToolkit
 from .terminal_toolkit import TerminalToolkit
 from .pubmed_toolkit import PubMedToolkit
 
-
 __all__ = [
     'BaseToolkit',
     'FunctionTool',
@@ -97,6 +97,7 @@ __all__ = [
     'ZapierToolkit',
     'SymPyToolkit',
     'MinerUToolkit',
+    'MemoryToolkit',
     'MCPToolkit',
     'MCPToolkitManager',
     'AudioAnalysisToolkit',