camel-ai 0.2.59__py3-none-any.whl → 0.2.82__py3-none-any.whl

camel/toolkits/jina_reranker_toolkit.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ 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
@@ -10,8 +10,12 @@
 # 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. =========
-from typing import List, Optional, Tuple
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+import json
+import os
+from typing import Any, Dict, List, Optional
+
+import requests
 
 from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
@@ -30,7 +34,9 @@ class JinaRerankerToolkit(BaseToolkit):
     def __init__(
         self,
         timeout: Optional[float] = None,
+        model_name: str = "jinaai/jina-reranker-m0",
         device: Optional[str] = None,
+        use_api: bool = True,
     ) -> None:
         r"""Initializes a new instance of the JinaRerankerToolkit class.
 
@@ -38,31 +44,56 @@ class JinaRerankerToolkit(BaseToolkit):
             timeout (Optional[float]): The timeout value for API requests
                 in seconds. If None, no timeout is applied.
                 (default: :obj:`None`)
+            model_name (str): The reranker model name.
+                (default: :obj:`"jinaai/jina-reranker-m0"`)
             device (Optional[str]): Device to load the model on. If None,
                 will use CUDA if available, otherwise CPU.
+                Only effective when use_api=False.
                 (default: :obj:`None`)
+            use_api (bool): A flag to switch between local model and API.
+                (default: :obj:`True`)
         """
-        import torch
-        from transformers import AutoModel
 
         super().__init__(timeout=timeout)
 
-        self.model = AutoModel.from_pretrained(
-            'jinaai/jina-reranker-m0',
-            torch_dtype="auto",
-            trust_remote_code=True,
-        )
-        DEVICE = (
-            device
-            if device is not None
-            else ("cuda" if torch.cuda.is_available() else "cpu")
-        )
-        self.model.to(DEVICE)
-        self.model.eval()
+        self.use_api = use_api
+        self.model_name = model_name
+
+        if self.use_api:
+            self.model = None
+            self._api_key = os.environ.get("JINA_API_KEY", "None")
+            if self._api_key == "None":
+                raise ValueError(
+                    "Missing or empty required API keys in "
+                    "environment variables\n"
+                    "You can obtain the API key from https://jina.ai/reranker/"
+                )
+            self.url = 'https://api.jina.ai/v1/rerank'
+            self.headers = {
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+                'Authorization': f'Bearer {self._api_key}',
+            }
+        else:
+            import torch
+            from transformers import AutoModel
+
+            self.model = AutoModel.from_pretrained(
+                self.model_name,
+                torch_dtype="auto",
+                trust_remote_code=True,
+            )
+            self.device = (
+                device
+                if device is not None
+                else ("cuda" if torch.cuda.is_available() else "cpu")
+            )
+            self.model.to(self.device)
+            self.model.eval()
 
     def _sort_documents(
         self, documents: List[str], scores: List[float]
-    ) -> List[Tuple[str, float]]:
+    ) -> List[Dict[str, object]]:
         r"""Sort documents by their scores in descending order.
 
         Args:
@@ -70,7 +101,7 @@ class JinaRerankerToolkit(BaseToolkit):
             scores (List[float]): Corresponding scores for each document.
 
         Returns:
-            List[Tuple[str, float]]: Sorted list of (document, score) pairs.
+            List[Dict[str, object]]: Sorted list of (document, score) pairs.
 
         Raises:
             ValueError: If documents and scores have different lengths.
@@ -80,14 +111,45 @@ class JinaRerankerToolkit(BaseToolkit):
         doc_score_pairs = list(zip(documents, scores))
         doc_score_pairs.sort(key=lambda x: x[1], reverse=True)
 
-        return doc_score_pairs
+        results = [
+            {'document': {'text': doc}, 'relevance_score': score}
+            for doc, score in doc_score_pairs
+        ]
+
+        return results
+
+    def _call_jina_api(self, data: Dict[str, Any]) -> List[Dict[str, object]]:
+        r"""Makes a call to the JINA API for reranking.
+
+        Args:
+            data (Dict[str]): The data to be passed into the api body.
+
+        Returns:
+            List[Dict[str, object]]: A list of dictionary containing
+                the reranked documents and their relevance scores.
+        """
+        try:
+            response = requests.post(
+                self.url,
+                headers=self.headers,
+                data=json.dumps(data),
+                timeout=self.timeout,
+            )
+            response.raise_for_status()
+            results = [
+                {key: value for key, value in _res.items() if key != 'index'}
+                for _res in response.json()['results']
+            ]
+            return results
+        except requests.exceptions.RequestException as e:
+            raise RuntimeError(f"Failed to get response from Jina AI: {e}")
 
     def rerank_text_documents(
         self,
         query: str,
         documents: List[str],
         max_length: int = 1024,
-    ) -> List[Tuple[str, float]]:
+    ) -> List[Dict[str, object]]:
         r"""Reranks text documents based on their relevance to a text query.
 
         Args:
@@ -97,21 +159,34 @@ class JinaRerankerToolkit(BaseToolkit):
                 (default: :obj:`1024`)
 
         Returns:
-            List[Tuple[str, float]]: A list of tuples containing
+            List[Dict[str, object]]: A list of dictionary containing
                 the reranked documents and their relevance scores.
         """
-        import torch
 
-        if self.model is None:
-            raise ValueError(
-                "Model has not been initialized or failed to initialize."
-            )
+        data = {
+            'model': self.model_name,
+            'query': query,
+            'top_n': len(documents),
+            'documents': documents,
+            'return_documents': True,
+        }
 
-        with torch.inference_mode():
-            text_pairs = [[query, doc] for doc in documents]
-            scores = self.model.compute_score(
-                text_pairs, max_length=max_length, doc_type="text"
-            )
+        if self.use_api:
+            return self._call_jina_api(data)
+
+        else:
+            import torch
+
+            if self.model is None:
+                raise ValueError(
+                    "Model has not been initialized or failed to initialize."
+                )
+
+            with torch.inference_mode():
+                text_pairs = [[query, doc] for doc in documents]
+                scores = self.model.compute_score(
+                    text_pairs, max_length=max_length, doc_type="text"
+                )
 
         return self._sort_documents(documents, scores)
 
@@ -120,7 +195,7 @@ class JinaRerankerToolkit(BaseToolkit):
         query: str,
         documents: List[str],
         max_length: int = 2048,
-    ) -> List[Tuple[str, float]]:
+    ) -> List[Dict[str, object]]:
         r"""Reranks image documents based on their relevance to a text query.
 
         Args:
@@ -130,21 +205,33 @@ class JinaRerankerToolkit(BaseToolkit):
                 (default: :obj:`2048`)
 
         Returns:
-            List[Tuple[str, float]]: A list of tuples containing
+            List[Dict[str, object]]: A list of dictionary containing
                 the reranked image URLs/paths and their relevance scores.
         """
-        import torch
-
-        if self.model is None:
-            raise ValueError(
-                "Model has not been initialized or failed to initialize."
-            )
-
-        with torch.inference_mode():
-            image_pairs = [[query, doc] for doc in documents]
-            scores = self.model.compute_score(
-                image_pairs, max_length=max_length, doc_type="image"
-            )
+        data = {
+            'model': self.model_name,
+            'query': query,
+            'top_n': len(documents),
+            'documents': documents,
+            'return_documents': True,
+        }
+
+        if self.use_api:
+            return self._call_jina_api(data)
+
+        else:
+            import torch
+
+            if self.model is None:
+                raise ValueError(
+                    "Model has not been initialized or failed to initialize."
+                )
+
+            with torch.inference_mode():
+                image_pairs = [[query, doc] for doc in documents]
+                scores = self.model.compute_score(
+                    image_pairs, max_length=max_length, doc_type="image"
+                )
 
         return self._sort_documents(documents, scores)
 
@@ -153,7 +240,7 @@ class JinaRerankerToolkit(BaseToolkit):
         image_query: str,
         documents: List[str],
         max_length: int = 2048,
-    ) -> List[Tuple[str, float]]:
+    ) -> List[Dict[str, object]]:
         r"""Reranks text documents based on their relevance to an image query.
 
         Args:
@@ -163,30 +250,45 @@ class JinaRerankerToolkit(BaseToolkit):
                 (default: :obj:`2048`)
 
         Returns:
-            List[Tuple[str, float]]: A list of tuples containing
+            List[Dict[str, object]]: A list of dictionary containing
                 the reranked documents and their relevance scores.
         """
-        import torch
-
-        if self.model is None:
-            raise ValueError("Model has not been initialized.")
-        with torch.inference_mode():
-            image_pairs = [[image_query, doc] for doc in documents]
-            scores = self.model.compute_score(
-                image_pairs,
-                max_length=max_length,
-                query_type="image",
-                doc_type="text",
-            )
-
-        return self._sort_documents(documents, scores)
+        data = {
+            'model': self.model_name,
+            'query': image_query,
+            'top_n': len(documents),
+            'documents': documents,
+            'return_documents': True,
+        }
+
+        if self.use_api:
+            return self._call_jina_api(data)
+
+        else:
+            import torch
+
+            if self.model is None:
+                raise ValueError(
+                    "Model has not been initialized or failed to initialize."
+                )
+
+            with torch.inference_mode():
+                image_pairs = [[image_query, doc] for doc in documents]
+                scores = self.model.compute_score(
+                    image_pairs,
+                    max_length=max_length,
+                    query_type="image",
+                    doc_type="text",
+                )
+
+            return self._sort_documents(documents, scores)
 
     def image_query_image_documents(
         self,
         image_query: str,
         documents: List[str],
         max_length: int = 2048,
-    ) -> List[Tuple[str, float]]:
+    ) -> List[Dict[str, object]]:
         r"""Reranks image documents based on their relevance to an image query.
 
         Args:
@@ -196,24 +298,38 @@ class JinaRerankerToolkit(BaseToolkit):
                 (default: :obj:`2048`)
 
         Returns:
-            List[Tuple[str, float]]: A list of tuples containing
+            List[Dict[str, object]]: A list of dictionary containing
                 the reranked image URLs/paths and their relevance scores.
         """
-        import torch
-
-        if self.model is None:
-            raise ValueError("Model has not been initialized.")
-
-        with torch.inference_mode():
-            image_pairs = [[image_query, doc] for doc in documents]
-            scores = self.model.compute_score(
-                image_pairs,
-                max_length=max_length,
-                query_type="image",
-                doc_type="image",
-            )
-
-        return self._sort_documents(documents, scores)
+        data = {
+            'model': self.model_name,
+            'query': image_query,
+            'top_n': len(documents),
+            'documents': documents,
+            'return_documents': True,
+        }
+
+        if self.use_api:
+            return self._call_jina_api(data)
+
+        else:
+            import torch
+
+            if self.model is None:
+                raise ValueError(
+                    "Model has not been initialized or failed to initialize."
+                )
+
+            with torch.inference_mode():
+                image_pairs = [[image_query, doc] for doc in documents]
+                scores = self.model.compute_score(
+                    image_pairs,
+                    max_length=max_length,
+                    query_type="image",
+                    doc_type="image",
+                )
+
+            return self._sort_documents(documents, scores)
 
     def get_tools(self) -> List[FunctionTool]:
         r"""Returns a list of FunctionTool objects representing the

camel/toolkits/klavis_toolkit.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ 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
@@ -10,7 +10,7 @@
 # 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. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 
 import os
 import urllib.parse
@@ -21,7 +21,11 @@ import requests
 from camel.logger import get_logger
 from camel.toolkits.base import BaseToolkit
 from camel.toolkits.function_tool import FunctionTool
-from camel.utils import MCPServer, api_keys_required, dependencies_required
+from camel.utils import (
+    MCPServer,
+    api_keys_required,
+    dependencies_required,
+)
 
 logger = get_logger(__name__)
 

camel/toolkits/linkedin_toolkit.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ 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
@@ -10,7 +10,7 @@
 # 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. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 
 import json
 import os

camel/toolkits/markitdown_toolkit.py

@@ -0,0 +1,104 @@
+# ========= Copyright 2023-2025 @ 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-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from typing import Dict, List, Optional
+
+from camel.loaders.markitdown import MarkItDownLoader
+from camel.logger import get_logger
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+from camel.utils import MCPServer
+
+logger = get_logger(__name__)
+
+
+@MCPServer()
+class MarkItDownToolkit(BaseToolkit):
+    r"""A class representing a toolkit for MarkItDown.
+
+    .. deprecated::
+        MarkItDownToolkit is deprecated. Use FileToolkit instead, which now
+        includes the same functionality through its read_file method that
+        supports both single files and multiple files.
+
+        Example migration:
+            # Old way
+            from camel.toolkits import MarkItDownToolkit
+            toolkit = MarkItDownToolkit()
+            content = toolkit.read_files(['file1.pdf', 'file2.docx'])
+
+            # New way
+            from camel.toolkits import FileToolkit
+            toolkit = FileToolkit()
+            content = toolkit.read_file(['file1.pdf', 'file2.docx'])
+    """
+
+    def __init__(
+        self,
+        timeout: Optional[float] = None,
+    ):
+        import warnings
+
+        warnings.warn(
+            "MarkItDownToolkit is deprecated and will be removed in a future "
+            "version. Please use FileToolkit instead, which now includes "
+            "read_file method that supports both single and multiple files.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(timeout=timeout)
+
+    def read_files(self, file_paths: List[str]) -> Dict[str, str]:
+        r"""Scrapes content from a list of files and converts it to Markdown.
+
+        This function takes a list of local file paths, attempts to convert
+        each file into Markdown format, and returns the converted content.
+        The conversion is performed in parallel for efficiency.
+
+        Supported file formats include:
+        - PDF (.pdf)
+        - Microsoft Office: Word (.doc, .docx), Excel (.xls, .xlsx),
+          PowerPoint (.ppt, .pptx)
+        - EPUB (.epub)
+        - HTML (.html, .htm)
+        - Images (.jpg, .jpeg, .png) for OCR
+        - Audio (.mp3, .wav) for transcription
+        - Text-based formats (.csv, .json, .xml, .txt)
+        - ZIP archives (.zip)
+
+        Args:
+            file_paths (List[str]): A list of local file paths to be
+                converted.
+
+        Returns:
+            Dict[str, str]: A dictionary where keys are the input file paths
+                and values are the corresponding content in Markdown format.
+                If conversion of a file fails, the value will contain an
+                error message.
+        """
+        return MarkItDownLoader().convert_files(
+            file_paths=file_paths, parallel=True
+        )
+
+    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.read_files),
+        ]

camel/toolkits/math_toolkit.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ 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
@@ -10,8 +10,9 @@
 # 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. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 
+import warnings
 from typing import List
 
 from camel.toolkits.base import BaseToolkit
@@ -27,7 +28,7 @@ class MathToolkit(BaseToolkit):
     addition, subtraction, multiplication, division, and rounding.
     """
 
-    def add(self, a: float, b: float) -> float:
+    def math_add(self, a: float, b: float) -> float:
         r"""Adds two numbers.
 
         Args:
@@ -39,7 +40,7 @@ class MathToolkit(BaseToolkit):
         """
         return a + b
 
-    def sub(self, a: float, b: float) -> float:
+    def math_subtract(self, a: float, b: float) -> float:
         r"""Do subtraction between two numbers.
 
         Args:
@@ -51,7 +52,9 @@ class MathToolkit(BaseToolkit):
         """
         return a - b
 
-    def multiply(self, a: float, b: float, decimal_places: int = 2) -> float:
+    def math_multiply(
+        self, a: float, b: float, decimal_places: int = 2
+    ) -> float:
         r"""Multiplies two numbers.
 
         Args:
@@ -65,7 +68,9 @@ class MathToolkit(BaseToolkit):
         """
         return round(a * b, decimal_places)
 
-    def divide(self, a: float, b: float, decimal_places: int = 2) -> float:
+    def math_divide(
+        self, a: float, b: float, decimal_places: int = 2
+    ) -> float:
         r"""Divides two numbers.
 
         Args:
@@ -79,7 +84,7 @@ class MathToolkit(BaseToolkit):
         """
         return round(a / b, decimal_places)
 
-    def round(self, a: float, decimal_places: int = 0) -> float:
+    def math_round(self, a: float, decimal_places: int = 0) -> float:
         r"""Rounds a number to a specified number of decimal places.
 
         Args:
@@ -101,9 +106,58 @@ class MathToolkit(BaseToolkit):
                 representing the functions in the toolkit.
         """
         return [
-            FunctionTool(self.add),
-            FunctionTool(self.sub),
-            FunctionTool(self.multiply),
-            FunctionTool(self.divide),
-            FunctionTool(self.round),
+            FunctionTool(self.math_add),
+            FunctionTool(self.math_subtract),
+            FunctionTool(self.math_multiply),
+            FunctionTool(self.math_divide),
+            FunctionTool(self.math_round),
         ]
+
+    # Deprecated method aliases for backward compatibility
+    def add(self, *args, **kwargs):
+        r"""Deprecated: Use math_add instead."""
+        warnings.warn(
+            "add is deprecated. Use math_add instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.math_add(*args, **kwargs)
+
+    def sub(self, *args, **kwargs):
+        r"""Deprecated: Use math_subtract instead."""
+        warnings.warn(
+            "sub is deprecated. Use math_subtract instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.math_subtract(*args, **kwargs)
+
+    def multiply(self, *args, **kwargs):
+        r"""Deprecated: Use math_multiply instead."""
+        warnings.warn(
+            "multiply is deprecated. Use math_multiply instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.math_multiply(*args, **kwargs)
+
+    def divide(self, *args, **kwargs):
+        r"""Deprecated: Use math_divide instead."""
+        warnings.warn(
+            "divide is deprecated. Use math_divide instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.math_divide(*args, **kwargs)
+
+    def round(self, *args, **kwargs):
+        r"""Deprecated: Use math_round instead. Note: This was shadowing
+        Python's built-in round().
+        """
+        warnings.warn(
+            "round is deprecated. Use math_round instead. This was "
+            "shadowing Python's built-in round().",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.math_round(*args, **kwargs)