camel-ai 0.2.75a6__py3-none-any.whl → 0.2.76a1__py3-none-any.whl

camel/utils/context_utils.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 os
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from camel.logger import get_logger
+
+if TYPE_CHECKING:
+    from camel.agents import ChatAgent
+    from camel.memories.records import MemoryRecord
+
+logger = get_logger(__name__)
+
+
+class ContextUtility:
+    r"""Utility class for context management and file operations.
+
+    This utility provides generic functionality for managing context files,
+    markdown generation, and session management that can be used by
+    context-related features.
+
+    Key features:
+    - Session-based directory management
+    - Generic markdown file operations
+    - Text-based search through files
+    - File metadata handling
+    - Agent memory record retrieval
+    """
+
+    def __init__(self, working_directory: Optional[str] = None):
+        r"""Initialize the ContextUtility.
+
+        Args:
+            working_directory (str, optional): The directory path where files
+                will be stored. If not provided, a default directory will be
+                used.
+        """
+        self.working_directory_param = working_directory
+        self._setup_storage(working_directory)
+
+    def _setup_storage(self, working_directory: Optional[str]) -> None:
+        r"""Initialize session-specific storage paths and create directory
+        structure for context file management."""
+        self.session_id = self._generate_session_id()
+
+        if working_directory:
+            self.working_directory = Path(working_directory).resolve()
+        else:
+            camel_workdir = os.environ.get("CAMEL_WORKDIR")
+            if camel_workdir:
+                self.working_directory = Path(camel_workdir) / "context_files"
+            else:
+                self.working_directory = Path("context_files")
+
+        # Create session-specific directory
+        self.working_directory = self.working_directory / self.session_id
+        self.working_directory.mkdir(parents=True, exist_ok=True)
+
+    def _generate_session_id(self) -> str:
+        r"""Create timestamp-based unique identifier for isolating
+        current session files from other sessions."""
+        timestamp = datetime.now().strftime('%Y%m%d_%H%M%S_%f')
+        return f"session_{timestamp}"
+
+    # ========= GENERIC FILE MANAGEMENT METHODS =========
+
+    def _create_or_update_note(self, note_name: str, content: str) -> str:
+        r"""Write content to markdown file, creating new file or
+        overwriting existing one with UTF-8 encoding.
+
+        Args:
+            note_name (str): Name of the note (without .md extension).
+            content (str): Content to write to the note.
+
+        Returns:
+            str: Success message.
+        """
+        try:
+            file_path = self.working_directory / f"{note_name}.md"
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(content)
+            return f"Note '{note_name}.md' created successfully"
+        except Exception as e:
+            logger.error(f"Error creating note {note_name}: {e}")
+            return f"Error creating note: {e}"
+
+    def save_markdown_file(
+        self,
+        filename: str,
+        content: str,
+        title: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        r"""Generic method to save any markdown content to a file.
+
+        Args:
+            filename (str): Name without .md extension.
+            content (str): Main content to save.
+            title (str, optional): Title for the markdown file.
+            metadata (Dict, optional): Additional metadata to include.
+
+        Returns:
+            str: Success message or error message.
+        """
+        try:
+            markdown_content = ""
+
+            # Add title if provided
+            if title:
+                markdown_content += f"# {title}\n\n"
+
+            # Add metadata section if provided
+            if metadata:
+                markdown_content += "## Metadata\n\n"
+                for key, value in metadata.items():
+                    markdown_content += f"- {key}: {value}\n"
+                markdown_content += "\n"
+
+            # Add main content
+            markdown_content += content
+
+            self._create_or_update_note(filename, markdown_content)
+            logger.info(
+                f"Markdown file saved to "
+                f"{self.working_directory / f'{filename}.md'}"
+            )
+            return f"Markdown file '{filename}.md' saved successfully"
+
+        except Exception as e:
+            logger.error(f"Error saving markdown file {filename}: {e}")
+            return f"Error saving markdown file: {e}"
+
+    def load_markdown_file(self, filename: str) -> str:
+        r"""Generic method to load any markdown file.
+
+        Args:
+            filename (str): Name without .md extension.
+
+        Returns:
+            str: File content or empty string if not found.
+        """
+        try:
+            file_path = self.working_directory / f"{filename}.md"
+            if file_path.exists():
+                return file_path.read_text(encoding="utf-8")
+            return ""
+        except Exception as e:
+            logger.error(f"Error loading markdown file {filename}: {e}")
+            return ""
+
+    def file_exists(self, filename: str) -> bool:
+        r"""Verify presence of markdown file in current session directory.
+
+        Args:
+            filename (str): Name without .md extension.
+
+        Returns:
+            bool: True if file exists, False otherwise.
+        """
+        file_path = self.working_directory / f"{filename}.md"
+        return file_path.exists()
+
+    def list_markdown_files(self) -> List[str]:
+        r"""Discover all markdown files in current session directory
+        and return their base names for reference.
+
+        Returns:
+            List[str]: List of filenames without .md extension.
+        """
+        try:
+            md_files = list(self.working_directory.glob("*.md"))
+            return [f.stem for f in md_files]
+        except Exception as e:
+            logger.error(f"Error listing markdown files: {e}")
+            return []
+
+    # ========= GENERIC AGENT MEMORY METHODS =========
+
+    def get_agent_memory_records(
+        self, agent: "ChatAgent"
+    ) -> List["MemoryRecord"]:
+        r"""Retrieve conversation history from agent's memory system.
+
+        Args:
+            agent (ChatAgent): The agent to extract memory records from.
+
+        Returns:
+            List[MemoryRecord]: List of memory records from the agent.
+        """
+        try:
+            context_records = agent.memory.retrieve()
+            return [cr.memory_record for cr in context_records]
+        except Exception as e:
+            logger.error(f"Error extracting memory records: {e}")
+            return []
+
+    def format_memory_as_conversation(
+        self, memory_records: List["MemoryRecord"]
+    ) -> str:
+        r"""Transform structured memory records into human-readable
+        conversation format with role labels and message content.
+
+        Args:
+            memory_records (List[MemoryRecord]): Memory records to format.
+
+        Returns:
+            str: Formatted conversation text.
+        """
+        conversation_lines = []
+
+        for record in memory_records:
+            role = (
+                record.role_at_backend.value
+                if hasattr(record.role_at_backend, 'value')
+                else str(record.role_at_backend)
+            )
+            content = record.message.content
+            conversation_lines.append(f"{role}: {content}")
+
+        return "\n".join(conversation_lines)
+
+    # ========= SESSION MANAGEMENT METHODS =========
+
+    def create_session_directory(
+        self, base_dir: Optional[str] = None, session_id: Optional[str] = None
+    ) -> Path:
+        r"""Create a session-specific directory.
+
+        Args:
+            base_dir (str, optional): Base directory. If None, uses current
+                working directory.
+            session_id (str, optional): Custom session ID. If None, generates
+                new one.
+
+        Returns:
+            Path: The created session directory path.
+        """
+        if session_id is None:
+            session_id = self._generate_session_id()
+
+        if base_dir:
+            base_path = Path(base_dir).resolve()
+        else:
+            base_path = self.working_directory.parent
+
+        session_dir = base_path / session_id
+        session_dir.mkdir(parents=True, exist_ok=True)
+        return session_dir
+
+    def get_session_metadata(self) -> Dict[str, Any]:
+        r"""Collect comprehensive session information including identifiers,
+        timestamps, and directory paths for tracking and reference.
+
+        Returns:
+            Dict[str, Any]: Session metadata including ID, timestamp,
+                directory.
+        """
+        return {
+            'session_id': self.session_id,
+            'working_directory': str(self.working_directory),
+            'created_at': datetime.now().isoformat(),
+            'base_directory': str(self.working_directory.parent),
+        }
+
+    def list_sessions(self, base_dir: Optional[str] = None) -> List[str]:
+        r"""Discover all available session directories for browsing
+        historical conversations and context files.
+
+        Args:
+            base_dir (str, optional): Base directory to search. If None, uses
+                parent of working directory.
+
+        Returns:
+            List[str]: List of session directory names.
+        """
+        try:
+            if base_dir:
+                search_dir = Path(base_dir)
+            else:
+                search_dir = self.working_directory.parent
+
+            session_dirs = [
+                d.name
+                for d in search_dir.iterdir()
+                if d.is_dir() and d.name.startswith('session_')
+            ]
+            return sorted(session_dirs)
+        except Exception as e:
+            logger.error(f"Error listing sessions: {e}")
+            return []
+
+    # ========= GENERIC SEARCH METHODS =========
+
+    def search_in_file(
+        self, file_path: Path, keywords: List[str], top_k: int = 4
+    ) -> str:
+        r"""Perform keyword-based search through file sections,
+        ranking results by keyword frequency and returning top matches.
+
+        Args:
+            file_path (Path): Path to the file to search.
+            keywords (List[str]): Keywords to search for.
+            top_k (int): Maximum number of results to return.
+
+        Returns:
+            str: Formatted search results.
+        """
+        results: List[Dict[str, Any]] = []
+        keyword_terms = [keyword.lower() for keyword in keywords]
+
+        try:
+            if not file_path.exists():
+                return ""
+
+            with open(file_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+
+            # Split content into sections (assuming ### headers)
+            sections = content.split('### ')[1:]  # Skip the header part
+
+            for i, section in enumerate(sections):
+                if not section.strip():
+                    continue
+
+                section_lower = section.lower()
+
+                # count how many keywords appear in this section
+                keyword_matches = sum(
+                    1 for keyword in keyword_terms if keyword in section_lower
+                )
+
+                if keyword_matches > 0:
+                    results.append(
+                        {
+                            'content': f"### {section.strip()}",
+                            'keyword_count': keyword_matches,
+                            'section_num': i + 1,
+                        }
+                    )
+
+        except Exception as e:
+            logger.warning(f"Error reading file {file_path}: {e}")
+            return ""
+
+        # sort by keyword count and limit results
+        results.sort(key=lambda x: x['keyword_count'], reverse=True)
+        results = results[:top_k]
+
+        if not results:
+            return ""
+
+        # format results
+        formatted_sections = []
+        for result in results:
+            formatted_sections.append(
+                f"Section {result['section_num']} "
+                f"(keyword matches: {result['keyword_count']}):\n"
+                f"{result['content']}\n"
+            )
+
+        return "\n---\n".join(formatted_sections)
+
+    # ========= UTILITY METHODS =========
+
+    def get_working_directory(self) -> Path:
+        r"""Retrieve the session-specific directory path where
+        all context files are stored.
+
+        Returns:
+            Path: The working directory path.
+        """
+        return self.working_directory
+
+    def get_session_id(self) -> str:
+        r"""Retrieve the unique identifier for the current session
+        used for file organization and tracking.
+
+        Returns:
+            str: The session ID.
+        """
+        return self.session_id

camel/utils/mcp.py

@@ -13,7 +13,121 @@
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import functools
 import inspect
-from typing import Any, Callable, Optional
+import warnings
+from typing import (
+    Any,
+    Callable,
+    List,
+    Optional,
+    Tuple,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from pydantic import create_model
+from pydantic.errors import PydanticSchemaGenerationError
+
+from camel.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def _is_pydantic_serializable(type_annotation: Any) -> Tuple[bool, str]:
+    r"""Check if a type annotation is Pydantic serializable.
+
+    Args:
+        type_annotation: The type annotation to check
+
+    Returns:
+        Tuple[bool, str]: (is_serializable, error_message)
+    """
+    # Handle None type
+    if type_annotation is type(None) or type_annotation is None:
+        return True, ""
+
+    # Handle generic types (List, Dict, Optional, etc.)
+    origin = get_origin(type_annotation)
+    if origin is not None:
+        args = get_args(type_annotation)
+
+        # For Union types (including Optional), check all args
+        if origin is Union:
+            for arg in args:
+                is_serializable, error_msg = _is_pydantic_serializable(arg)
+                if not is_serializable:
+                    return False, error_msg
+            return True, ""
+
+        # For List, Set, Tuple, etc., check the contained types
+        if origin in (list, set, tuple, frozenset):
+            for arg in args:
+                is_serializable, error_msg = _is_pydantic_serializable(arg)
+                if not is_serializable:
+                    return False, error_msg
+            return True, ""
+
+        # For Dict, check both key and value types
+        if origin is dict:
+            for arg in args:
+                is_serializable, error_msg = _is_pydantic_serializable(arg)
+                if not is_serializable:
+                    return False, error_msg
+            return True, ""
+
+    # Try to create a simple pydantic model with this type
+    try:
+        create_model("TestModel", test_field=(type_annotation, ...))
+        # If model creation succeeds, the type is serializable
+        return True, ""
+    except (PydanticSchemaGenerationError, TypeError, ValueError) as e:
+        error_msg = (
+            f"Type '{type_annotation}' is not Pydantic serializable. "
+            f"Consider using a custom serializable type or converting "
+            f"to bytes/base64. Error: {e!s}"
+        )
+        return False, error_msg
+
+
+def _validate_function_types(func: Callable[..., Any]) -> List[str]:
+    r"""Validate function parameter and return types are Pydantic serializable.
+
+    Args:
+        func (Callable[..., Any]): The function to validate.
+
+    Returns:
+        List[str]: List of error messages for incompatible types.
+    """
+    errors = []
+
+    try:
+        type_hints = get_type_hints(func)
+    except (NameError, AttributeError) as e:
+        # If we can't get type hints, skip validation
+        logger.warning(f"Could not get type hints for {func.__name__}: {e}")
+        return []
+
+    # Check return type
+    return_type = type_hints.get('return', Any)
+    if return_type != Any:
+        is_serializable, error_msg = _is_pydantic_serializable(return_type)
+        if not is_serializable:
+            errors.append(f"Return type: {error_msg}")
+
+    # Check parameter types
+    sig = inspect.signature(func)
+    for param_name, _param in sig.parameters.items():
+        if param_name == 'self':
+            continue
+
+        param_type = type_hints.get(param_name, Any)
+        if param_type != Any:
+            is_serializable, error_msg = _is_pydantic_serializable(param_type)
+            if not is_serializable:
+                errors.append(f"Parameter '{param_name}': {error_msg}")
+
+    return errors
 
 
 class MCPServer:
@@ -55,7 +169,7 @@ class MCPServer:
 
     def __init__(
         self,
-        function_names: Optional[list[str]] = None,
+        function_names: Optional[List[str]] = None,
         server_name: Optional[str] = None,
     ):
         self.function_names = function_names
@@ -135,6 +249,26 @@ class MCPServer:
                         f"Method {name} not found in class {cls.__name__} or "
                         "cannot be called."
                     )
+
+                # Validate function types for Pydantic compatibility
+                type_errors = _validate_function_types(func)
+                if type_errors:
+                    error_message = (
+                        f"Method '{name}' in class '{cls.__name__}' has "
+                        f"non-Pydantic-serializable types:\n"
+                        + "\n".join(f"  - {error}" for error in type_errors)
+                        + "\n\nSuggestions:"
+                        + "\n  - Use standard Python types (str, int, float, bool, bytes)"  # noqa: E501
+                        + "\n  - Convert complex objects to JSON strings or bytes"  # noqa: E501
+                        + "\n  - Create custom Pydantic models for complex data"  # noqa: E501
+                        + "\n  - Use base64 encoding for binary data like images"  # noqa: E501
+                    )
+
+                    # For now, issue a warning instead of raising an error
+                    # This allows gradual migration while alerting developers
+                    warnings.warn(error_message, UserWarning, stacklevel=3)
+                    logger.warning(error_message)
+
                 wrapper = self.make_wrapper(func)
                 instance.mcp.tool(name=name)(wrapper)
 

{camel_ai-0.2.75a6.dist-info → camel_ai-0.2.76a1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: camel-ai
-Version: 0.2.75a6
+Version: 0.2.76a1
 Summary: Communicative Agents for AI Society Study
 Project-URL: Homepage, https://www.camel-ai.org/
 Project-URL: Repository, https://github.com/camel-ai/camel
@@ -39,7 +39,7 @@ Requires-Dist: dappier<0.4,>=0.3.3; extra == 'all'
 Requires-Dist: datacommons-pandas<0.0.4,>=0.0.3; extra == 'all'
 Requires-Dist: datacommons<2,>=1.4.3; extra == 'all'
 Requires-Dist: datasets<4,>=3; extra == 'all'
-Requires-Dist: daytona-sdk==0.20.0; extra == 'all'
+Requires-Dist: daytona-sdk>=0.20.0; extra == 'all'
 Requires-Dist: diffusers<0.26,>=0.25.0; extra == 'all'
 Requires-Dist: discord-py<3,>=2.3.2; extra == 'all'
 Requires-Dist: docker<8,>=7.1.0; extra == 'all'
@@ -57,6 +57,7 @@ Requires-Dist: flask>=2.0; extra == 'all'
 Requires-Dist: google-api-python-client==2.166.0; extra == 'all'
 Requires-Dist: google-auth-httplib2==0.2.0; extra == 'all'
 Requires-Dist: google-auth-oauthlib==1.2.1; extra == 'all'
+Requires-Dist: google-cloud-aiplatform>=1.111.0; extra == 'all'
 Requires-Dist: google-cloud-storage<3,>=2.18.0; extra == 'all'
 Requires-Dist: google-genai>=1.13.0; extra == 'all'
 Requires-Dist: googlemaps<5,>=4.10.0; extra == 'all'
@@ -73,6 +74,7 @@ Requires-Dist: markitdown>=0.1.1; extra == 'all'
 Requires-Dist: math-verify<0.8,>=0.7.0; extra == 'all'
 Requires-Dist: mcp>=1.3.0; extra == 'all'
 Requires-Dist: mem0ai>=0.1.67; extra == 'all'
+Requires-Dist: microsandbox>=0.1.8; extra == 'all'
 Requires-Dist: mistralai<2,>=1.1.0; extra == 'all'
 Requires-Dist: mock<6,>=5; extra == 'all'
 Requires-Dist: mypy<2,>=1.5.1; extra == 'all'
@@ -186,13 +188,14 @@ Requires-Dist: uv<0.8,>=0.7.0; extra == 'dev'
 Provides-Extra: dev-tools
 Requires-Dist: aci-sdk>=1.0.0b1; extra == 'dev-tools'
 Requires-Dist: agentops<0.4,>=0.3.21; extra == 'dev-tools'
-Requires-Dist: daytona-sdk==0.20.0; extra == 'dev-tools'
+Requires-Dist: daytona-sdk>=0.20.0; extra == 'dev-tools'
 Requires-Dist: docker<8,>=7.1.0; extra == 'dev-tools'
 Requires-Dist: e2b-code-interpreter<2,>=1.0.3; extra == 'dev-tools'
 Requires-Dist: ipykernel<7,>=6.0.0; extra == 'dev-tools'
 Requires-Dist: jupyter-client<9,>=8.6.2; extra == 'dev-tools'
 Requires-Dist: langfuse>=2.60.5; extra == 'dev-tools'
 Requires-Dist: mcp>=1.3.0; extra == 'dev-tools'
+Requires-Dist: microsandbox>=0.1.8; extra == 'dev-tools'
 Requires-Dist: tree-sitter-python<0.24,>=0.23.6; extra == 'dev-tools'
 Requires-Dist: tree-sitter<0.24,>=0.23.2; extra == 'dev-tools'
 Requires-Dist: typer>=0.15.2; extra == 'dev-tools'