camel-ai 0.2.75a5__py3-none-any.whl → 0.2.76__py3-none-any.whl

camel/interpreters/microsandbox_interpreter.py

@@ -0,0 +1,395 @@
+# ========= 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 asyncio
+from typing import Any, ClassVar, Dict, List, Optional, Tuple, Union
+
+from camel.interpreters.base import BaseInterpreter
+from camel.interpreters.interpreter_error import InterpreterError
+from camel.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class MicrosandboxInterpreter(BaseInterpreter):
+    r"""Microsandbox Code Interpreter implementation.
+
+    This interpreter provides secure code execution using microsandbox,
+    a self-hosted platform for secure execution of untrusted user/AI code.
+    It supports Python code execution via PythonSandbox, JavaScript/Node.js
+    code execution via NodeSandbox, and shell commands via the command
+    interface.
+
+    Args:
+        require_confirm (bool, optional): If True, prompt user before running
+            code strings for security. (default: :obj:`True`)
+        server_url (str, optional): URL of the microsandbox server. If not
+            provided, will use MSB_SERVER_URL environment variable, then
+            fall back to http://127.0.0.1:5555. (default: :obj:`None`)
+        api_key (str, optional): API key for microsandbox authentication.
+            If not provided, will use MSB_API_KEY environment variable.
+            (default: :obj:`None`)
+        namespace (str, optional): Namespace for the sandbox.
+            (default: :obj:`"default"`)
+        sandbox_name (str, optional): Name of the sandbox instance. If not
+            provided, a random name will be generated by the SDK.
+            (default: :obj:`None`)
+        timeout (int, optional): Default timeout for code execution in seconds.
+            (default: :obj:`30`)
+
+    Environment Variables:
+        MSB_SERVER_URL: URL of the microsandbox server.
+        MSB_API_KEY: API key for microsandbox authentication.
+
+    Note:
+        The SDK handles parameter priority as: user parameter > environment
+            variable > default value.
+    """
+
+    _CODE_TYPE_MAPPING: ClassVar[Dict[str, str]] = {
+        # Python code - uses PythonSandbox
+        "python": "python_sandbox",
+        "py3": "python_sandbox",
+        "python3": "python_sandbox",
+        "py": "python_sandbox",
+        # JavaScript/Node.js code - uses NodeSandbox
+        "javascript": "node_sandbox",
+        "js": "node_sandbox",
+        "node": "node_sandbox",
+        "typescript": "node_sandbox",
+        "ts": "node_sandbox",
+        # Shell commands - uses command.run()
+        "bash": "shell_command",
+        "shell": "shell_command",
+        "sh": "shell_command",
+    }
+
+    def __init__(
+        self,
+        require_confirm: bool = True,
+        server_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        namespace: str = "default",
+        sandbox_name: Optional[str] = None,
+        timeout: int = 30,
+    ) -> None:
+        from microsandbox import (
+            NodeSandbox,
+            PythonSandbox,
+        )
+
+        # Store parameters, let SDK handle defaults and environment variables
+        self.require_confirm = require_confirm
+        self.server_url = server_url  # None means use SDK default logic
+        self.api_key = api_key  # None means use SDK default logic
+        self.namespace = namespace
+        self.sandbox_name = (
+            sandbox_name  # None means SDK generates random name
+        )
+        self.timeout = timeout
+
+        # Store sandbox configuration
+        self._sandbox_config = {
+            "server_url": self.server_url,
+            "namespace": self.namespace,
+            "name": self.sandbox_name,
+            "api_key": self.api_key,
+        }
+
+        # Store sandbox classes for reuse
+        self._PythonSandbox = PythonSandbox
+        self._NodeSandbox = NodeSandbox
+
+        # Log initialization info
+        logger.info("Initialized MicrosandboxInterpreter")
+        logger.info(f"Namespace: {self.namespace}")
+        if self.sandbox_name:
+            logger.info(f"Sandbox name: {self.sandbox_name}")
+        else:
+            logger.info("Sandbox name: will be auto-generated by SDK")
+
+    def run(
+        self,
+        code: str,
+        code_type: str = "python",
+    ) -> str:
+        r"""Executes the given code in the microsandbox.
+
+        Args:
+            code (str): The code string to execute.
+            code_type (str): The type of code to execute. Supported types:
+                'python', 'javascript', 'bash'. (default: :obj:`python`)
+
+        Returns:
+            str: The string representation of the output of the executed code.
+
+        Raises:
+            InterpreterError: If the `code_type` is not supported or if any
+                runtime error occurs during the execution of the code.
+        """
+        if code_type not in self._CODE_TYPE_MAPPING:
+            raise InterpreterError(
+                f"Unsupported code type {code_type}. "
+                f"`{self.__class__.__name__}` only supports "
+                f"{', '.join(list(self._CODE_TYPE_MAPPING.keys()))}."
+            )
+
+        # Print code for security checking
+        if self.require_confirm:
+            logger.info(
+                f"The following {code_type} code will run on "
+                f"microsandbox: {code}"
+            )
+            self._confirm_execution("code")
+
+        # Run the code asynchronously
+        return asyncio.run(self._run_async(code, code_type))
+
+    async def _run_async(self, code: str, code_type: str) -> str:
+        r"""Asynchronously executes code in microsandbox.
+
+        Args:
+            code (str): The code to execute.
+            code_type (str): The type of code to execute.
+
+        Returns:
+            str: The output of the executed code.
+
+        Raises:
+            InterpreterError: If execution fails.
+        """
+        try:
+            execution_method = self._CODE_TYPE_MAPPING[code_type]
+
+            if execution_method == "python_sandbox":
+                return await self._run_python_code(code)
+            elif execution_method == "node_sandbox":
+                return await self._run_node_code(code)
+            elif execution_method == "shell_command":
+                return await self._run_shell_command(code)
+            else:
+                raise InterpreterError(
+                    f"Unsupported execution method: {execution_method}"
+                )
+
+        except Exception as e:
+            raise InterpreterError(
+                f"Error executing code in microsandbox: {e}"
+            )
+
+    async def _run_python_code(self, code: str) -> str:
+        r"""Execute Python code using PythonSandbox.
+
+        Args:
+            code (str): Python code to execute.
+
+        Returns:
+            str: Execution output.
+        """
+        async with self._PythonSandbox.create(
+            **self._sandbox_config
+        ) as sandbox:
+            execution = await asyncio.wait_for(
+                sandbox.run(code), timeout=self.timeout
+            )
+            return await self._get_execution_output(execution)
+
+    async def _run_node_code(self, code: str) -> str:
+        r"""Execute JavaScript/Node.js code using NodeSandbox.
+
+        Args:
+            code (str): JavaScript/Node.js code to execute.
+
+        Returns:
+            str: Execution output.
+        """
+        async with self._NodeSandbox.create(**self._sandbox_config) as sandbox:
+            execution = await asyncio.wait_for(
+                sandbox.run(code), timeout=self.timeout
+            )
+            return await self._get_execution_output(execution)
+
+    async def _run_shell_command(self, code: str) -> str:
+        r"""Execute shell commands directly.
+
+        Args:
+            code (str): Shell command to execute.
+
+        Returns:
+            str: Command execution output.
+        """
+        # Use any sandbox for shell commands
+        async with self._PythonSandbox.create(
+            **self._sandbox_config
+        ) as sandbox:
+            execution = await asyncio.wait_for(
+                sandbox.command.run("bash", ["-c", code]), timeout=self.timeout
+            )
+            return await self._get_command_output(execution)
+
+    async def _get_execution_output(self, execution) -> str:
+        r"""Get output from code execution.
+
+        Args:
+            execution: Execution object from sandbox.run().
+
+        Returns:
+            str: Formatted execution output.
+        """
+        output = await execution.output()
+        error = await execution.error()
+
+        result_parts = []
+        if output and output.strip():
+            result_parts.append(output.strip())
+        if error and error.strip():
+            result_parts.append(f"STDERR: {error.strip()}")
+
+        return (
+            "\n".join(result_parts)
+            if result_parts
+            else "Code executed successfully (no output)"
+        )
+
+    async def _get_command_output(self, execution) -> str:
+        r"""Get output from command execution.
+
+        Args:
+            execution: CommandExecution object from sandbox.command.run().
+
+        Returns:
+            str: Formatted command output.
+        """
+        output = await execution.output()
+        error = await execution.error()
+
+        result_parts = []
+        if output and output.strip():
+            result_parts.append(output.strip())
+        if error and error.strip():
+            result_parts.append(f"STDERR: {error.strip()}")
+        if hasattr(execution, 'exit_code') and execution.exit_code != 0:
+            result_parts.append(f"Exit code: {execution.exit_code}")
+
+        return (
+            "\n".join(result_parts)
+            if result_parts
+            else "Command executed successfully (no output)"
+        )
+
+    def _confirm_execution(self, execution_type: str) -> None:
+        r"""Prompt user for confirmation before executing code or commands.
+
+        Args:
+            execution_type (str): Type of execution ('code' or 'command').
+
+        Raises:
+            InterpreterError: If user declines to run the code/command.
+        """
+        while True:
+            choice = input(f"Running {execution_type}? [Y/n]:").lower()
+            if choice in ["y", "yes", "ye"]:
+                break
+            elif choice not in ["no", "n"]:
+                continue
+            raise InterpreterError(
+                f"Execution halted: User opted not to run the "
+                f"{execution_type}. "
+                f"This choice stops the current operation and any "
+                f"further {execution_type} execution."
+            )
+
+    def supported_code_types(self) -> List[str]:
+        r"""Provides supported code types by the interpreter."""
+        return list(self._CODE_TYPE_MAPPING.keys())
+
+    def update_action_space(self, action_space: Dict[str, Any]) -> None:
+        r"""Updates action space for interpreter.
+
+        Args:
+            action_space: Action space dictionary (unused in microsandbox).
+
+        Note:
+            Microsandbox doesn't support action space updates as it runs
+            in isolated environments for each execution.
+        """
+        # Explicitly acknowledge the parameter to avoid linting warnings
+        _ = action_space
+        logger.warning(
+            "Microsandbox doesn't support action space updates. "
+            "Code runs in isolated environments for each execution."
+        )
+
+    def execute_command(self, command: str) -> Union[str, Tuple[str, str]]:
+        r"""Execute a shell command in the microsandbox.
+
+        This method is designed for package management and system
+        administration tasks. It executes shell commands directly
+        using the microsandbox command interface.
+
+        Args:
+            command (str): The shell command to execute (e.g.,
+            "pip install numpy", "ls -la", "apt-get update").
+
+        Returns:
+            Union[str, Tuple[str, str]]: The output of the command.
+
+        Examples:
+            >>> interpreter.execute_command("pip install numpy")
+            >>> interpreter.execute_command("npm install express")
+            >>> interpreter.execute_command("ls -la /tmp")
+        """
+        # Print command for security checking
+        if self.require_confirm:
+            logger.info(
+                f"The following shell command will run on "
+                f"microsandbox: {command}"
+            )
+            self._confirm_execution("command")
+
+        return asyncio.run(self._execute_command_async(command))
+
+    async def _execute_command_async(self, command: str) -> str:
+        r"""Asynchronously executes a shell command in microsandbox.
+
+        Args:
+            command (str): The shell command to execute.
+
+        Returns:
+            str: The output of the command execution.
+
+        Raises:
+            InterpreterError: If execution fails.
+        """
+        try:
+            async with self._PythonSandbox.create(
+                **self._sandbox_config
+            ) as sandbox:
+                execution = await asyncio.wait_for(
+                    sandbox.command.run("bash", ["-c", command]),
+                    timeout=self.timeout,
+                )
+                return await self._get_command_output(execution)
+
+        except Exception as e:
+            raise InterpreterError(
+                f"Error executing command in microsandbox: {e}"
+            )
+
+    def __del__(self) -> None:
+        r"""Destructor for the MicrosandboxInterpreter class.
+
+        Microsandbox uses context managers for resource management,
+        so no explicit cleanup is needed.
+        """
+        logger.debug("MicrosandboxInterpreter cleaned up")

camel/loaders/__init__.py

@@ -21,7 +21,6 @@ from .jina_url_reader import JinaURLReader
 from .markitdown import MarkItDownLoader
 from .mineru_extractor import MinerU
 from .mistral_reader import MistralReader
-from .pandas_reader import PandasReader
 from .scrapegraph_reader import ScrapeGraphAI
 from .unstructured_io import UnstructuredIO
 
@@ -33,7 +32,6 @@ __all__ = [
     'JinaURLReader',
     'Firecrawl',
     'Apify',
-    'PandasReader',
     'ChunkrReader',
     'ChunkrReaderConfig',
     'MinerU',
@@ -42,3 +40,14 @@ __all__ = [
     'ScrapeGraphAI',
     'MistralReader',
 ]
+
+
+def __getattr__(name: str):
+    if name == 'PandasReader':
+        raise ImportError(
+            "PandasReader has been removed from camel.loaders. "
+            "The pandasai dependency limited pandas to version 1.5.3. "
+            "Please use ExcelToolkit from camel.toolkits instead for "
+            "handling structured data."
+        )
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

camel/loaders/chunkr_reader.py

@@ -34,6 +34,12 @@ class ChunkrReaderConfig:
         high_resolution (bool, optional): Whether to use high resolution OCR.
             (default: :obj:`True`)
         ocr_strategy (str, optional): The OCR strategy. Defaults to 'Auto'.
+        **kwargs: Additional keyword arguments to pass to the Chunkr
+            Configuration. This accepts all other Configuration parameters
+            such as expires_in, pipeline, segment_processing,
+            segmentation_strategy, etc.
+            See: https://github.com/lumina-ai-inc/chunkr/blob/main/core/src/
+            models/task.rs#L749
     """
 
     def __init__(
@@ -41,10 +47,12 @@ class ChunkrReaderConfig:
         chunk_processing: int = 512,
         high_resolution: bool = True,
         ocr_strategy: str = "Auto",
+        **kwargs,
     ):
         self.chunk_processing = chunk_processing
         self.high_resolution = high_resolution
         self.ocr_strategy = ocr_strategy
+        self.kwargs = kwargs
 
 
 class ChunkrReader:
@@ -190,4 +198,5 @@ class ChunkrReader:
                 "Auto": OcrStrategy.AUTO,
                 "All": OcrStrategy.ALL,
             }.get(chunkr_config.ocr_strategy, OcrStrategy.ALL),
+            **chunkr_config.kwargs,
         )

camel/memories/__init__.py

@@ -18,7 +18,7 @@ from .agent_memories import (
     VectorDBMemory,
 )
 from .base import AgentMemory, BaseContextCreator, MemoryBlock
-from .blocks.chat_history_block import ChatHistoryBlock
+from .blocks.chat_history_block import ChatHistoryBlock, EmptyMemoryWarning
 from .blocks.vectordb_block import VectorDBBlock
 from .context_creators.score_based import ScoreBasedContextCreator
 from .records import ContextRecord, MemoryRecord
@@ -35,4 +35,5 @@ __all__ = [
     'ChatHistoryBlock',
     'VectorDBBlock',
     'LongtermAgentMemory',
+    'EmptyMemoryWarning',
 ]

camel/memories/agent_memories.py

@@ -51,7 +51,9 @@ class ChatHistoryMemory(AgentMemory):
             raise ValueError("`window_size` must be non-negative.")
         self._context_creator = context_creator
         self._window_size = window_size
-        self._chat_history_block = ChatHistoryBlock(storage=storage)
+        self._chat_history_block = ChatHistoryBlock(
+            storage=storage,
+        )
         self._agent_id = agent_id
 
     @property

camel/memories/blocks/chat_history_block.py

@@ -21,6 +21,17 @@ from camel.storages.key_value_storages.in_memory import InMemoryKeyValueStorage
 from camel.types import OpenAIBackendRole
 
 
+class EmptyMemoryWarning(UserWarning):
+    """Warning raised when attempting to access an empty memory.
+
+    This warning is raised when operations are performed on memory
+    that contains no records. It can be safely caught and suppressed
+    in contexts where empty memory is expected.
+    """
+
+    pass
+
+
 class ChatHistoryBlock(MemoryBlock):
     r"""An implementation of the :obj:`MemoryBlock` abstract base class for
     maintaining a record of chat histories.
@@ -39,7 +50,7 @@ class ChatHistoryBlock(MemoryBlock):
             last message is 1.0, and with each step taken backward, the score
             of the message is multiplied by the `keep_rate`. Higher `keep_rate`
             leads to high possibility to keep history messages during context
-            creation.
+            creation. (default: :obj:`0.9`)
     """
 
     def __init__(
@@ -70,7 +81,11 @@ class ChatHistoryBlock(MemoryBlock):
         """
         record_dicts = self.storage.load()
         if len(record_dicts) == 0:
-            warnings.warn("The `ChatHistoryMemory` is empty.")
+            warnings.warn(
+                "The `ChatHistoryMemory` is empty.",
+                EmptyMemoryWarning,
+                stacklevel=1,
+            )
             return list()
 
         if window_size is not None and window_size >= 0:
@@ -81,7 +96,10 @@ class ChatHistoryBlock(MemoryBlock):
                 if (
                     record_dicts
                     and record_dicts[0]['role_at_backend']
-                    in {OpenAIBackendRole.SYSTEM, OpenAIBackendRole.DEVELOPER}
+                    in {
+                        OpenAIBackendRole.SYSTEM.value,
+                        OpenAIBackendRole.DEVELOPER.value,
+                    }
                 )
                 else 0
             )

camel/memories/records.py

@@ -15,8 +15,8 @@
 # Enables postponed evaluation of annotations (for string-based type hints)
 from __future__ import annotations
 
+import inspect
 import time
-from dataclasses import asdict
 from typing import Any, ClassVar, Dict
 from uuid import UUID, uuid4
 
@@ -63,6 +63,20 @@ class MemoryRecord(BaseModel):
         "FunctionCallingMessage": FunctionCallingMessage,
     }
 
+    # Cache for constructor parameters (performance optimization)
+    _constructor_params_cache: ClassVar[Dict[str, set]] = {}
+
+    @classmethod
+    def _get_constructor_params(cls, message_cls) -> set:
+        """Get constructor parameters for a message class with caching."""
+        cls_name = message_cls.__name__
+        if cls_name not in cls._constructor_params_cache:
+            sig = inspect.signature(message_cls.__init__)
+            cls._constructor_params_cache[cls_name] = set(
+                sig.parameters.keys()
+            ) - {'self'}
+        return cls._constructor_params_cache[cls_name]
+
     @classmethod
     def from_dict(cls, record_dict: Dict[str, Any]) -> "MemoryRecord":
         r"""Reconstruct a :obj:`MemoryRecord` from the input dict.
@@ -70,14 +84,78 @@ class MemoryRecord(BaseModel):
         Args:
             record_dict(Dict[str, Any]): A dict generated by :meth:`to_dict`.
         """
+        from camel.types import OpenAIBackendRole, RoleType
+
         message_cls = cls._MESSAGE_TYPES[record_dict["message"]["__class__"]]
-        kwargs: Dict = record_dict["message"].copy()
-        kwargs.pop("__class__")
-        reconstructed_message = message_cls(**kwargs)
+        data = record_dict["message"].copy()
+        data.pop("__class__")
+
+        # Convert role_type string to enum
+        if "role_type" in data and isinstance(data["role_type"], str):
+            data["role_type"] = RoleType(data["role_type"])
+
+        # Deserialize image_list from base64 strings/URLs back to PIL Images/
+        # URLs
+        if "image_list" in data and data["image_list"] is not None:
+            import base64
+            from io import BytesIO
+
+            from PIL import Image
+
+            image_objects = []
+            for img_item in data["image_list"]:
+                if isinstance(img_item, dict):
+                    # New format with type indicator
+                    if img_item["type"] == "url":
+                        # URL string, keep as-is
+                        image_objects.append(img_item["data"])
+                    else:  # type == "base64"
+                        # Base64 encoded image, convert to PIL Image
+                        img_bytes = base64.b64decode(img_item["data"])
+                        img = Image.open(BytesIO(img_bytes))
+                        # Restore the format attribute if it was saved
+                        if "format" in img_item:
+                            img.format = img_item["format"]
+                        image_objects.append(img)
+                else:
+                    # Legacy format: assume it's a base64 string
+                    img_bytes = base64.b64decode(img_item)
+                    img = Image.open(BytesIO(img_bytes))
+                    image_objects.append(img)
+            data["image_list"] = image_objects
+
+        # Deserialize video_bytes from base64 string
+        if "video_bytes" in data and data["video_bytes"] is not None:
+            import base64
+
+            data["video_bytes"] = base64.b64decode(data["video_bytes"])
+
+        # Get valid constructor parameters (cached)
+        valid_params = cls._get_constructor_params(message_cls)
+
+        # Separate constructor args from extra fields
+        kwargs = {k: v for k, v in data.items() if k in valid_params}
+        extra_fields = {k: v for k, v in data.items() if k not in valid_params}
+
+        # Handle meta_dict properly: merge existing meta_dict with extra fields
+        existing_meta = kwargs.get("meta_dict", {}) or {}
+        if extra_fields:
+            # Extra fields take precedence, but preserve existing meta_dict
+            # structure
+            merged_meta = {**existing_meta, **extra_fields}
+            kwargs["meta_dict"] = merged_meta
+        elif not existing_meta:
+            kwargs["meta_dict"] = None
+
+        # Convert role_at_backend
+        role_at_backend = record_dict["role_at_backend"]
+        if isinstance(role_at_backend, str):
+            role_at_backend = OpenAIBackendRole(role_at_backend)
+
         return cls(
             uuid=UUID(record_dict["uuid"]),
-            message=reconstructed_message,
-            role_at_backend=record_dict["role_at_backend"],
+            message=message_cls(**kwargs),
+            role_at_backend=role_at_backend,
             extra_info=record_dict["extra_info"],
             timestamp=record_dict["timestamp"],
             agent_id=record_dict["agent_id"],
@@ -91,9 +169,11 @@ class MemoryRecord(BaseModel):
             "uuid": str(self.uuid),
             "message": {
                 "__class__": self.message.__class__.__name__,
-                **asdict(self.message),
+                **self.message.to_dict(),
             },
-            "role_at_backend": self.role_at_backend,
+            "role_at_backend": self.role_at_backend.value
+            if hasattr(self.role_at_backend, "value")
+            else self.role_at_backend,
             "extra_info": self.extra_info,
             "timestamp": self.timestamp,
             "agent_id": self.agent_id,