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

camel/datasets/static_dataset.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,9 +10,10 @@
 # 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 random
+from collections.abc import Sequence
 from pathlib import Path
 from typing import (
     Any,
@@ -288,6 +289,11 @@ class StaticDataset(Dataset):
             )
         raw_data = []
 
+        if not isinstance(data, Sequence):
+            raise TypeError(
+                f"{type(data).__name__} does not support indexing."
+            )
+
         for i in range(len(data)):
             item = data[i]
             if not isinstance(item, dict):
@@ -398,3 +404,147 @@ class StaticDataset(Dataset):
                     f"got {type(item).__name__}"
                 )
         return data
+
+    def save_to_json(self, file_path: Union[str, Path]) -> None:
+        r"""Save the dataset to a local JSON file.
+
+        Args:
+            file_path (Union[str, Path]): Path to the output JSON file.
+                If a string is provided, it will be converted to a Path object.
+
+        Raises:
+            TypeError: If file_path is not a string or Path object.
+            OSError: If there's an error writing to the file.
+        """
+        if isinstance(file_path, str):
+            file_path = Path(file_path)
+        elif not isinstance(file_path, Path):
+            raise TypeError(
+                f"Expected file_path to be a string or Path object, "
+                f"got {type(file_path).__name__}"
+            )
+
+        # Convert DataPoint objects to dictionaries
+        data_dicts = [datapoint.to_dict() for datapoint in self.data]
+
+        # Ensure the parent directory exists
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            logger.debug(f"Saving dataset to {file_path}")
+            with file_path.open('w', encoding='utf-8') as f:
+                json.dump(data_dicts, f, ensure_ascii=False, indent=2)
+            logger.info(
+                f"Successfully saved {len(data_dicts)} items to {file_path}"
+            )
+        except OSError as e:
+            logger.error(f"Error saving dataset to {file_path}: {e}")
+            raise
+
+    def save_to_huggingface(
+        self,
+        dataset_name: str,
+        token: Optional[str] = None,
+        filepath: str = "records/records.json",
+        private: bool = False,
+        description: Optional[str] = None,
+        license: Optional[str] = None,
+        version: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        language: Optional[List[str]] = None,
+        task_categories: Optional[List[str]] = None,
+        authors: Optional[List[str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        r"""Save the dataset to the Hugging Face Hub using the project's
+        HuggingFaceDatasetManager.
+
+        Args:
+            dataset_name (str): The name of the dataset on Hugging Face Hub.
+                Should be in the format 'username/dataset_name' .
+            token (Optional[str]): The Hugging Face API token. If not provided,
+                the token will be read from the environment variable `HF_TOKEN`
+                (default: :obj:`None`)
+            filepath (str): The path in the repository where the dataset
+                will be saved.  (default: :obj:`"records/records.json"`)
+            private (bool): Whether the dataset should be private.
+                (default: :obj:`False`)
+            description (Optional[str]): A description of the dataset.
+                (default: :obj:`None`)
+            license (Optional[str]): The license of the dataset.
+                (default: :obj:`None`)
+            version (Optional[str]): The version of the dataset.
+                (default: :obj:`None`)
+            tags (Optional[List[str]]): A list of tags for the dataset.
+                (default: :obj:`None`)
+            language (Optional[List[str]]): A list of languages the dataset is
+                in. (default: :obj:`None`)
+            task_categories (Optional[List[str]]): A list of task categories.
+                (default: :obj:`None`)
+            authors (Optional[List[str]]): A list of authors of the dataset.
+                (default: :obj:`None`)
+            **kwargs (Any): Additional keyword arguments to pass to the
+                Hugging Face API.
+
+        Returns:
+            str: The URL of the dataset on the Hugging Face Hub.
+
+        Raises:
+            OSError: If there's an error uploading the dataset.
+        """
+        # lazy import to avoid heavy dependencies
+        from camel.datahubs.huggingface import HuggingFaceDatasetManager
+        from camel.datahubs.models import Record
+
+        # Initialize the HuggingFaceDatasetManager
+        manager = HuggingFaceDatasetManager(token=token)
+
+        # Convert DataPoint objects to Record objects
+        records = []
+        for datapoint in self.data:
+            datapoint_dict = datapoint.to_dict()
+
+            record_dict = {
+                "question": datapoint_dict.get("question", ""),
+                "final_answer": datapoint_dict.get("final_answer", ""),
+                "rationale": datapoint_dict.get("rationale", ""),
+                "metadata": datapoint_dict.get("metadata", {}),
+            }
+            record = Record(**record_dict)
+            records.append(record)
+
+        logger.debug(f"Creating dataset {dataset_name}")
+        try:
+            # Create the dataset
+            dataset_url = manager.create_dataset(
+                name=dataset_name, private=private, **kwargs
+            )
+
+            # Add records to the dataset
+            manager.add_records(
+                dataset_name=dataset_name,
+                records=records,
+                filepath=filepath,
+            )
+
+            # Create dataset card if description is provided
+            if description:
+                manager.create_dataset_card(
+                    dataset_name=dataset_name,
+                    description=description,
+                    license=license,
+                    version=version,
+                    tags=tags,
+                    authors=authors,
+                    language=language,
+                    task_categories=task_categories,
+                )
+
+            logger.info(
+                f"Successfully uploaded dataset to {dataset_name}, "
+                f"the url is {dataset_url}"
+            )
+            return dataset_url
+        except Exception as e:
+            logger.error(f"Error uploading dataset to Hugging Face: {e}")
+            raise

camel/embeddings/__init__.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. =========
 from .azure_embedding import AzureEmbedding
 from .base import BaseEmbedding
 from .gemini_embedding import GeminiEmbedding

camel/embeddings/azure_embedding.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. =========
 
 
 from __future__ import annotations

camel/embeddings/base.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. =========
 from __future__ import annotations
 
 from abc import ABC, abstractmethod

camel/embeddings/gemini_embedding.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. =========
 from __future__ import annotations
 
 import os

camel/embeddings/jina_embedding.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,10 @@
 # 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. =========
+
+# Enables postponed evaluation of annotations (for string-based type hints)
+from __future__ import annotations
 
 import base64
 import io
@@ -104,6 +107,7 @@ class JinaEmbedding(BaseEmbedding[Union[str, Image.Image]]):
             ValueError: If the input type is not supported.
             RuntimeError: If the API request fails.
         """
+
         input_data = []
         for obj in objs:
             if isinstance(obj, str):
@@ -111,7 +115,10 @@ class JinaEmbedding(BaseEmbedding[Union[str, Image.Image]]):
                     input_data.append({"text": obj})
                 else:
                     input_data.append(obj)  # type: ignore[arg-type]
-            elif isinstance(obj, Image.Image):
+            elif (
+                obj.__class__.__module__ == "PIL.Image"
+                and obj.__class__.__name__ == "Image"
+            ):
                 if self.model_type != EmbeddingModelType.JINA_CLIP_V2:
                     raise ValueError(
                         f"Model {self.model_type} does not support "

camel/embeddings/mistral_embedding.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. =========
 from __future__ import annotations
 
 import os

camel/embeddings/openai_compatible_embedding.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. =========
 from __future__ import annotations
 
 import os

camel/embeddings/openai_embedding.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. =========
 from __future__ import annotations
 
 import os

camel/embeddings/sentence_transformers_embeddings.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,13 +10,11 @@
 # 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. =========
 from __future__ import annotations
 
 from typing import Any
 
-from numpy import ndarray
-
 from camel.embeddings.base import BaseEmbedding
 
 
@@ -61,6 +59,8 @@ class SentenceTransformerEncoder(BaseEmbedding[str]):
             list[list[float]]: A list that represents the generated embedding
                 as a list of floating-point numbers.
         """
+        from numpy import ndarray
+
         if not objs:
             raise ValueError("Input text list is empty")
         embeddings = self.model.encode(

camel/embeddings/together_embedding.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
 from typing import Any, Optional
 

camel/embeddings/vlm_embedding.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,11 @@
 # 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. =========
+
+# Enables postponed evaluation of annotations (for string-based type hints)
+from __future__ import annotations
+
 from typing import Any, List, Optional, Union
 
 from PIL import Image
@@ -70,7 +74,7 @@ class VisionLanguageEmbedding(BaseEmbedding[Union[str, Image.Image]]):
     def embed_list(
         self, objs: List[Union[Image.Image, str]], **kwargs: Any
     ) -> List[List[float]]:
-        """Generates embeddings for the given images or texts.
+        r"""Generates embeddings for the given images or texts.
 
         Args:
             objs (List[Image.Image|str]): The list of images or texts for
@@ -98,7 +102,10 @@ class VisionLanguageEmbedding(BaseEmbedding[Union[str, Image.Image]]):
 
         result_list = []
         for obj in objs:
-            if isinstance(obj, Image.Image):
+            if (
+                obj.__class__.__module__ == "PIL.Image"
+                and obj.__class__.__name__ == "Image"
+            ):
                 image_input = self.processor(
                     images=obj,
                     return_tensors="pt",

camel/environments/__init__.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,9 +10,16 @@
 # 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. =========
 from .models import Action, Environment, Observation, StepResult
 from .multi_step import MultiStepEnv
+from .rlcards_env import (
+    ActionExtractor,
+    BlackjackEnv,
+    DoudizhuEnv,
+    LeducHoldemEnv,
+    RLCardsEnv,
+)
 from .single_step import SingleStepEnv
 from .tic_tac_toe import Opponent, TicTacToeEnv
 
@@ -25,4 +32,9 @@ __all__ = [
     "StepResult",
     "TicTacToeEnv",
     "Opponent",
+    "RLCardsEnv",
+    "BlackjackEnv",
+    "LeducHoldemEnv",
+    "ActionExtractor",
+    "DoudizhuEnv",
 ]

camel/environments/models.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. =========
 
 from datetime import datetime, timezone
 from typing import Any, Dict, Optional, Protocol, Tuple

camel/environments/multi_step.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. =========
 
 from abc import ABC, abstractmethod
 from typing import Any, Dict, List, Optional, Tuple