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

camel/utils/deduplication.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 typing import Dict, List, Literal, Optional

camel/utils/filename.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 platform
 import re
 import unicodedata

camel/utils/langfuse.py

@@ -0,0 +1,258 @@
+# ========= 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. =========
+import os
+import threading
+from typing import Any, Dict, List, Optional
+
+from camel.logger import get_logger
+from camel.utils import dependencies_required
+
+logger = get_logger(__name__)
+# Thread-local storage for agent session IDs
+_local = threading.local()
+
+# Global flag to track if Langfuse has been configured
+_langfuse_configured = False
+
+try:
+    from langfuse.decorators import langfuse_context
+
+    LANGFUSE_AVAILABLE = True
+except ImportError:
+    LANGFUSE_AVAILABLE = False
+
+
+@dependencies_required('langfuse')
+def configure_langfuse(
+    public_key: Optional[str] = None,
+    secret_key: Optional[str] = None,
+    host: Optional[str] = None,
+    debug: Optional[bool] = None,
+    enabled: Optional[bool] = None,
+):
+    r"""Configure Langfuse for CAMEL models.
+
+    Args:
+        public_key(Optional[str]): Langfuse public key. Can be set via LANGFUSE_PUBLIC_KEY.
+            (default: :obj:`None`)
+        secret_key(Optional[str]): Langfuse secret key. Can be set via LANGFUSE_SECRET_KEY.
+            (default: :obj:`None`)
+        host(Optional[str]): Langfuse host URL. Can be set via LANGFUSE_HOST.
+            (default: :obj:`https://cloud.langfuse.com`)
+        debug(Optional[bool]): Enable debug mode. Can be set via LANGFUSE_DEBUG.
+            (default: :obj:`None`)
+        enabled(Optional[bool]): Enable/disable tracing. Can be set via LANGFUSE_ENABLED.
+            (default: :obj:`None`)
+
+    Note:
+        This function configures the native langfuse_context which works with
+            @observe() decorators. Set enabled=False to disable all tracing.
+    """  # noqa: E501
+    global _langfuse_configured
+
+    # Get configuration from environment or parameters
+    public_key = public_key or os.environ.get("LANGFUSE_PUBLIC_KEY")
+    secret_key = secret_key or os.environ.get("LANGFUSE_SECRET_KEY")
+    host = host or os.environ.get(
+        "LANGFUSE_HOST", "https://cloud.langfuse.com"
+    )
+    debug = (
+        debug
+        if debug is not None
+        else os.environ.get("LANGFUSE_DEBUG", "False").lower() == "true"
+    )
+
+    # Handle enabled parameter
+    if enabled is None:
+        env_enabled_str = os.environ.get("LANGFUSE_ENABLED")
+        if env_enabled_str is not None:
+            enabled = env_enabled_str.lower() == "true"
+        else:
+            enabled = False  # Default to disabled
+
+    # If not enabled, don't configure anything and don't call langfuse function
+    if not enabled:
+        _langfuse_configured = False
+        logger.info("Langfuse tracing disabled for CAMEL models")
+
+    logger.debug(
+        f"Configuring Langfuse - enabled: {enabled}, "
+        f"public_key: {'***' + public_key[-4:] if public_key else None}, "
+        f"host: {host}, debug: {debug}"
+    )
+    if enabled and public_key and secret_key and LANGFUSE_AVAILABLE:
+        _langfuse_configured = True
+    else:
+        _langfuse_configured = False
+
+    try:
+        # Configure langfuse_context with native method
+        langfuse_context.configure(
+            public_key=public_key,
+            secret_key=secret_key,
+            host=host,
+            debug=debug,
+            enabled=True,  # Always True here since we checked enabled above
+        )
+
+        logger.info("Langfuse tracing enabled for CAMEL models")
+
+    except Exception as e:
+        logger.error(f"Failed to configure Langfuse: {e}")
+
+
+def is_langfuse_available() -> bool:
+    r"""Check if Langfuse is configured."""
+    return _langfuse_configured
+
+
+def set_current_agent_session_id(session_id: str) -> None:
+    r"""Set the session ID for the current agent in thread-local storage.
+
+    Args:
+        session_id(str): The session ID to set for the current agent.
+    """
+
+    _local.agent_session_id = session_id
+
+
+def get_current_agent_session_id() -> Optional[str]:
+    r"""Get the session ID for the current agent from thread-local storage.
+
+    Returns:
+        Optional[str]: The session ID for the current agent.
+    """
+    if is_langfuse_available():
+        return getattr(_local, 'agent_session_id', None)
+    return None
+
+
+def update_langfuse_trace(
+    session_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    tags: Optional[List[str]] = None,
+) -> bool:
+    r"""Update the current Langfuse trace with session ID and metadata.
+
+    Args:
+        session_id(Optional[str]): Optional session ID to use. If :obj:`None`
+            uses the current agent's session ID. (default: :obj:`None`)
+        user_id(Optional[str]): Optional user ID for the trace.
+            (default: :obj:`None`)
+        metadata(Optional[Dict[str, Any]]): Optional metadata dictionary.
+            (default: :obj:`None`)
+        tags(Optional[List[str]]): Optional list of tags.
+            (default: :obj:`None`)
+
+    Returns:
+        bool: True if update was successful, False otherwise.
+    """
+    if not is_langfuse_available():
+        return False
+
+    # Use provided session_id or get from thread-local storage
+    final_session_id = session_id or get_current_agent_session_id()
+
+    update_data: Dict[str, Any] = {}
+    if final_session_id:
+        update_data["session_id"] = final_session_id
+    if user_id:
+        update_data["user_id"] = user_id
+    if metadata:
+        update_data["metadata"] = metadata
+    if tags:
+        update_data["tags"] = tags
+
+    if update_data:
+        langfuse_context.update_current_trace(**update_data)
+        return True
+
+    return False
+
+
+def update_current_observation(
+    input: Optional[Dict[str, Any]] = None,
+    output: Optional[Dict[str, Any]] = None,
+    model: Optional[str] = None,
+    model_parameters: Optional[Dict[str, Any]] = None,
+    usage_details: Optional[Dict[str, Any]] = None,
+    **kwargs,
+) -> None:
+    r"""Update the current Langfuse observation with input, output,
+    model, model_parameters, and usage_details.
+
+    Args:
+        input(Optional[Dict[str, Any]]): Optional input dictionary.
+            (default: :obj:`None`)
+        output(Optional[Dict[str, Any]]): Optional output dictionary.
+            (default: :obj:`None`)
+        model(Optional[str]): Optional model name. (default: :obj:`None`)
+        model_parameters(Optional[Dict[str, Any]]): Optional model parameters
+            dictionary. (default: :obj:`None`)
+        usage_details(Optional[Dict[str, Any]]): Optional usage details
+            dictionary. (default: :obj:`None`)
+
+    Returns:
+        None
+    """
+    if not is_langfuse_available():
+        return
+
+    langfuse_context.update_current_observation(
+        input=input,
+        output=output,
+        model=model,
+        model_parameters=model_parameters,
+        usage_details=usage_details,
+        **kwargs,
+    )
+
+
+def get_langfuse_status() -> Dict[str, Any]:
+    r"""Get detailed Langfuse configuration status for debugging.
+
+    Returns:
+        Dict[str, Any]: Status information including configuration state.
+    """
+    env_enabled_str = os.environ.get("LANGFUSE_ENABLED")
+    env_enabled = (
+        env_enabled_str.lower() == "true" if env_enabled_str else None
+    )
+
+    status = {
+        "configured": _langfuse_configured,
+        "has_public_key": bool(os.environ.get("LANGFUSE_PUBLIC_KEY")),
+        "has_secret_key": bool(os.environ.get("LANGFUSE_SECRET_KEY")),
+        "env_enabled": env_enabled,
+        "host": os.environ.get("LANGFUSE_HOST", "https://cloud.langfuse.com"),
+        "debug": os.environ.get("LANGFUSE_DEBUG", "false").lower() == "true",
+        "current_session_id": get_current_agent_session_id(),
+    }
+
+    if _langfuse_configured:
+        try:
+            # Try to get some context information
+            status["langfuse_context_available"] = True
+        except Exception as e:
+            status["langfuse_context_error"] = str(e)
+
+    return status
+
+
+def observe(*args, **kwargs):
+    def decorator(func):
+        return func
+
+    return decorator

camel/utils/mcp.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,10 +10,124 @@
 # 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 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
@@ -106,11 +220,11 @@ class MCPServer:
         """
         from mcp.server.fastmcp import FastMCP
 
-        from camel.toolkits.base import BaseToolkit
-
         original_init = cls.__init__
 
         def new_init(instance, *args, **kwargs):
+            from camel.toolkits.base import BaseToolkit
+
             original_init(instance, *args, **kwargs)
             self.server_name = self.server_name or cls.__name__
             instance.mcp = FastMCP(self.server_name)
@@ -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)