camel-ai 0.2.65__py3-none-any.whl → 0.2.83a6__py3-none-any.whl

camel/toolkits/message_integration.py

@@ -0,0 +1,728 @@
+# ========= Copyright 2023-2026 @ 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-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+import inspect
+from functools import wraps
+from typing import Callable, List, Optional, Union
+
+from camel.logger import get_logger
+from camel.toolkits import BaseToolkit, FunctionTool
+
+logger = get_logger(__name__)
+
+
+class ToolkitMessageIntegration:
+    r"""Integrates user messaging capabilities into CAMEL toolkits and
+    functions.
+
+    This class allows agents to send status updates to users while executing
+    toolkit functions in a single step, improving communication and reducing
+    the number of tool calls needed.
+
+    Supports both built-in and custom message handlers with flexible parameter
+    names. Can update both toolkit methods and standalone functions.
+
+    Example:
+        >>> # Using default message handler with toolkit
+        >>> message_integration = ToolkitMessageIntegration()
+        >>> search_with_messaging = message_integration.
+        register_toolkits(
+        ...     SearchToolkit()
+        ... )
+
+        >>> # Using with standalone functions
+        >>> def search_web(query: str) -> list:
+        ...     return ["result1", "result2"]
+        ...
+        >>> enhanced_tools = message_integration.register_functions
+        ([search_web])
+
+        >>> # Using custom message handler with different parameters
+        >>> def notify_user(severity: str, action: str, details: str = "") ->
+        str:
+        ...     '''Send notification to user.
+        ...
+        ...     Args:
+        ...         severity: Notification level (info/warning/error)
+        ...         action: What action is being performed
+        ...         details: Additional details
+        ...     '''
+        ...     print(f"[{severity}] {action}: {details}")
+        ...     return "Notified"
+        ...
+        >>> message_integration = ToolkitMessageIntegration(
+        ...     message_handler=notify_user,
+        ...     extract_params_callback=lambda kwargs: (
+        ...         kwargs.pop('severity', 'info'),
+        ...         kwargs.pop('action', 'executing'),
+        ...         kwargs.pop('details', '')
+        ...     )
+        ... )
+    """
+
+    def __init__(
+        self,
+        message_handler: Optional[Callable] = None,
+        extract_params_callback: Optional[Callable[[dict], tuple]] = None,
+    ):
+        r"""Initialize the toolkit message integration.
+
+        Args:
+            message_handler (Optional[Callable]): Custom message handler
+                function. If not provided, uses the built-in
+                send_message_to_user. (default: :obj:`None`)
+            extract_params_callback (Optional[Callable]): Function to extract
+                parameters from kwargs for the custom message handler. Should
+                return a tuple of arguments to pass to the message handler. If
+                not provided, uses default extraction for built-in handler.
+                (default: :obj:`None`)
+        """
+        self.message_handler = message_handler or self.send_message_to_user
+        self.extract_params_callback = (
+            extract_params_callback or self._default_extract_params
+        )
+
+        # If custom handler is provided, we'll use its signature and docstring
+        self.use_custom_handler = message_handler is not None
+
+    def _default_extract_params(self, kwargs: dict) -> tuple:
+        r"""Default parameter extraction for built-in message handler."""
+        return (
+            kwargs.pop('message_title', ''),
+            kwargs.pop('message_description', ''),
+            kwargs.pop('message_attachment', ''),
+        )
+
+    def send_message_to_user(
+        self,
+        message_title: str,
+        message_description: str,
+        message_attachment: str = "",
+    ) -> str:
+        r"""Built-in message handler that sends tidy messages to the user.
+
+        This one-way tool keeps the user informed about agent progress,
+        decisions, or actions. It does not require a response.
+
+        Args:
+            message_title (str): The title of the message.
+            message_description (str): The short description message.
+            message_attachment (str): The additional attachment of the message,
+                which can be a file path or a URL.
+
+        Returns:
+            str: Confirmation that the message was successfully sent.
+        """
+        print(f"\nAgent Message:\n{message_title}\n{message_description}\n")
+        if message_attachment:
+            print(message_attachment)
+
+        logger.info(
+            f"\nAgent Message:\n{message_title} "
+            f"{message_description} {message_attachment}"
+        )
+
+        return (
+            f"Message successfully sent to user: '{message_title} "
+            f"{message_description} {message_attachment}'"
+        )
+
+    def get_message_tool(self) -> FunctionTool:
+        r"""Get the send_message_to_user as a standalone FunctionTool.
+
+        This can be used when you want to provide the messaging capability
+        as a separate tool rather than integrating it into other tools.
+
+        Returns:
+            FunctionTool: The message sending tool.
+        """
+        return FunctionTool(self.send_message_to_user)
+
+    def register_toolkits(self, toolkit: BaseToolkit) -> BaseToolkit:
+        r"""Add messaging capabilities to all toolkit methods.
+
+        This method modifies a toolkit so that all its tools can send
+        status messages to users while executing their primary function.
+        The tools will accept optional messaging parameters:
+        - message_title: Title of the status message
+        - message_description: Description of what the tool is doing
+        - message_attachment: Optional file path or URL
+
+        Args:
+            toolkit: The toolkit to add messaging capabilities to
+
+        Returns:
+            The same toolkit instance with messaging capabilities added to
+                all methods.
+        """
+        original_tools = toolkit.get_tools()
+        enhanced_methods = {}
+        for tool in original_tools:
+            method_name = tool.func.__name__
+            enhanced_func = self._add_messaging_to_tool(tool.func)
+            enhanced_func = self._create_bound_method_wrapper(
+                enhanced_func,
+                toolkit,
+            )
+            enhanced_methods[method_name] = enhanced_func
+            setattr(toolkit, method_name, enhanced_func)
+        original_get_tools_method = toolkit.get_tools
+
+        def enhanced_get_tools() -> List[FunctionTool]:
+            tools = []
+            for _, enhanced_method in enhanced_methods.items():
+                tools.append(FunctionTool(enhanced_method))
+            original_tools_list = original_get_tools_method()
+            for tool in original_tools_list:
+                if tool.func.__name__ not in enhanced_methods:
+                    tools.append(tool)
+
+            return tools
+
+        toolkit.get_tools = enhanced_get_tools  # type: ignore[method-assign]
+
+        # Also handle clone_for_new_session
+        # if it exists to ensure cloned toolkits
+        # also have message integration
+        if hasattr(toolkit, 'clone_for_new_session'):
+            original_clone_method = toolkit.clone_for_new_session
+            message_integration_instance = self
+
+            def enhanced_clone_for_new_session(new_session_id=None):
+                cloned_toolkit = original_clone_method(new_session_id)
+                return message_integration_instance.register_toolkits(
+                    cloned_toolkit
+                )
+
+            toolkit.clone_for_new_session = enhanced_clone_for_new_session
+
+        return toolkit
+
+    def _create_bound_method_wrapper(
+        self, enhanced_func: Callable, toolkit_instance
+    ) -> Callable:
+        r"""Create a wrapper that mimics a bound method for _clone_tools.
+
+        This wrapper preserves the toolkit instance reference while maintaining
+        the enhanced messaging functionality.
+        """
+
+        # Create a wrapper that appears as a bound method to _clone_tools
+        @wraps(enhanced_func)
+        def bound_method_wrapper(*args, **kwargs):
+            return enhanced_func(*args, **kwargs)
+
+        # Make it appear as a bound method by setting __self__
+        bound_method_wrapper.__self__ = toolkit_instance  # type: ignore[attr-defined]
+
+        # Preserve other important attributes
+        if hasattr(enhanced_func, '__signature__'):
+            bound_method_wrapper.__signature__ = enhanced_func.__signature__  # type: ignore[attr-defined]
+        if hasattr(enhanced_func, '__doc__'):
+            bound_method_wrapper.__doc__ = enhanced_func.__doc__
+
+        return bound_method_wrapper
+
+    def register_functions(
+        self,
+        functions: Union[List[FunctionTool], List[Callable]],
+        function_names: Optional[List[str]] = None,
+    ) -> List[FunctionTool]:
+        r"""Add messaging capabilities to a list of functions or FunctionTools.
+
+        This method enhances functions so they can send status messages to
+        users while executing. The enhanced functions will accept optional
+        messaging parameters that trigger status updates.
+
+        Args:
+            functions (Union[List[FunctionTool], List[Callable]]): List of
+                FunctionTool objects or callable functions to enhance.
+            function_names (Optional[List[str]]): List of specific function
+                names to modify. If None, messaging is added to all functions.
+
+        Returns:
+            List[FunctionTool]: List of enhanced FunctionTool objects
+
+        Example:
+            >>> # With FunctionTools
+            >>> tools = [FunctionTool(search_func), FunctionTool(analyze_func)]
+            >>> enhanced_tools = message_integration.register_functions
+            (tools)
+
+            >>> # With callable functions
+            >>> funcs = [search_web, analyze_data, generate_report]
+            >>> enhanced_tools = message_integration.register_functions
+            (
+            ...     funcs,
+            ...     function_names=['search_web', 'analyze_data']
+            ... )
+        """
+        enhanced_tools = []
+
+        for item in functions:
+            # Extract the function based on input type
+            if isinstance(item, FunctionTool):
+                func = item.func
+            elif callable(item):
+                func = item
+            else:
+                raise ValueError(
+                    f"Invalid item type: {type(item)}. Expected "
+                    f"FunctionTool or callable."
+                )
+
+            # Check if this function should be enhanced
+            if function_names is None or func.__name__ in function_names:
+                enhanced_func = self._add_messaging_to_tool(func)
+                enhanced_tools.append(FunctionTool(enhanced_func))
+            else:
+                # Return as FunctionTool regardless of input type
+                if isinstance(item, FunctionTool):
+                    enhanced_tools.append(item)
+                else:
+                    enhanced_tools.append(FunctionTool(func))
+
+        return enhanced_tools
+
+    def _add_messaging_to_tool(self, func: Callable) -> Callable:
+        r"""Add messaging parameters to a tool function.
+
+        This internal method modifies the function signature and docstring
+        to include optional messaging parameters that trigger status updates.
+        """
+        if getattr(func, "__message_integration_enhanced__", False):
+            logger.debug(
+                f"Function {func.__name__} already enhanced, skipping"
+            )
+            return func
+
+        # Get the original signature
+        original_sig = inspect.signature(func)
+
+        # Check if the function is async
+        is_async = inspect.iscoroutinefunction(func)
+
+        # Create new parameters for the enhanced function
+        new_params = list(original_sig.parameters.values())
+
+        # Determine which parameters to add based on handler type
+        if self.use_custom_handler:
+            # Use the custom handler's signature
+            handler_sig = inspect.signature(self.message_handler)
+            message_params = []
+
+            # Add parameters from the custom handler (excluding self if it's a
+            # method)
+            for param_name, param in handler_sig.parameters.items():
+                if param_name != 'self':
+                    # Create a keyword-only parameter with the same annotation
+                    # and default
+                    new_param = inspect.Parameter(
+                        param_name,
+                        inspect.Parameter.KEYWORD_ONLY,
+                        default=param.default
+                        if param.default != inspect.Parameter.empty
+                        else None,
+                        annotation=param.annotation
+                        if param.annotation != inspect.Parameter.empty
+                        else inspect.Parameter.empty,
+                    )
+                    message_params.append(new_param)
+        else:
+            # Use default parameters for built-in handler
+            message_params = [
+                inspect.Parameter(
+                    'message_title',
+                    inspect.Parameter.KEYWORD_ONLY,
+                    default="",
+                    annotation=str,
+                ),
+                inspect.Parameter(
+                    'message_description',
+                    inspect.Parameter.KEYWORD_ONLY,
+                    default="",
+                    annotation=str,
+                ),
+                inspect.Parameter(
+                    'message_attachment',
+                    inspect.Parameter.KEYWORD_ONLY,
+                    default="",
+                    annotation=str,
+                ),
+            ]
+
+        # Find where to insert the new parameters (before **kwargs if it
+        # exists)
+        insert_index = len(new_params)
+        for i, param in enumerate(new_params):
+            if param.kind == inspect.Parameter.VAR_KEYWORD:
+                insert_index = i
+                break
+
+        # Insert the message parameters
+        for param in reversed(message_params):
+            new_params.insert(insert_index, param)
+
+        # Create the new signature
+        new_sig = original_sig.replace(parameters=new_params)
+
+        if is_async:
+
+            @wraps(func)
+            async def wrapper(*args, **kwargs):
+                try:
+                    params = self.extract_params_callback(kwargs)
+                except KeyError:
+                    return await func(*args, **kwargs)
+
+                # Check if we should send a message
+                should_send = False
+                if self.use_custom_handler:
+                    should_send = any(
+                        p is not None and p != '' for p in params
+                    )
+                else:
+                    # For default handler, params
+                    # (title, description, attachment)
+                    should_send = bool(params[0]) or bool(params[1])
+
+                # Send message if needed (handle async properly)
+                if should_send:
+                    try:
+                        if self.use_custom_handler:
+                            # Check if message handler is async
+                            if inspect.iscoroutinefunction(
+                                self.message_handler
+                            ):
+                                await self.message_handler(*params)
+                            else:
+                                self.message_handler(*params)
+                        else:
+                            # For built-in handler, provide defaults
+                            title, desc, attach = params
+                            self.message_handler(
+                                title or "Executing Tool",
+                                desc or f"Running {func.__name__}",
+                                attach or '',
+                            )
+                    except Exception as msg_error:
+                        # Don't let message handler
+                        # errors break the main function
+                        logger.warning(f"Message handler error: {msg_error}")
+
+                # Execute the original function
+                # (kwargs have been modified to remove message params)
+                result = await func(*args, **kwargs)
+
+                return result
+        else:
+
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                # Extract parameters using the callback
+                # (this will modify kwargs by removing message params)
+                try:
+                    params = self.extract_params_callback(kwargs)
+                except KeyError:
+                    # If parameters are missing,
+                    # just execute the original function
+                    return func(*args, **kwargs)
+
+                # Check if we should send a message
+                should_send = False
+                if self.use_custom_handler:
+                    should_send = any(
+                        p is not None and p != '' for p in params
+                    )
+                else:
+                    should_send = bool(params[0]) or bool(params[1])
+
+                # Send message if needed
+                if should_send:
+                    try:
+                        if self.use_custom_handler:
+                            self.message_handler(*params)
+                        else:
+                            # For built-in handler, provide defaults
+                            title, desc, attach = params
+                            self.message_handler(
+                                title or "Executing Tool",
+                                desc or f"Running {func.__name__}",
+                                attach or '',
+                            )
+                    except Exception as msg_error:
+                        logger.warning(f"Message handler error: {msg_error}")
+
+                result = func(*args, **kwargs)
+
+                return result
+
+        # Apply the new signature to the wrapper
+        wrapper.__signature__ = new_sig  # type: ignore[attr-defined]
+
+        # Mark this function as enhanced by message integration
+        wrapper.__message_integration_enhanced__ = True  # type: ignore[attr-defined]
+
+        # Create a hybrid approach:
+        # store toolkit instance info but preserve calling behavior
+        # We'll use a property-like
+        # approach to make __self__ available when needed
+        if hasattr(func, '__self__'):
+            toolkit_instance = func.__self__
+
+            # Store the toolkit instance as an attribute
+            # Use setattr to avoid MyPy type checking issues
+            wrapper.__toolkit_instance__ = toolkit_instance  # type: ignore[attr-defined]
+
+            # Create a dynamic __self__ property
+            # that only appears during introspection
+            # but doesn't interfere with normal function calls
+            def get_self():
+                return toolkit_instance
+
+            # Only set __self__
+            # if we're being called in an introspection context
+            # (like from _clone_tools)
+            # Use setattr to avoid MyPy type checking issues
+            wrapper.__self__ = toolkit_instance  # type: ignore[attr-defined]
+
+        # Enhance the docstring
+        if func.__doc__:
+            enhanced_doc = func.__doc__.rstrip()
+            lines = enhanced_doc.split('\n')
+
+            # Find where to insert parameters
+            insert_idx = self._find_docstring_insert_point(lines)
+
+            # Check if we need to create an Args section
+            has_args_section = any(
+                'Args:' in line
+                or 'Arguments:' in line
+                or 'Parameters:' in line
+                for line in lines
+            )
+
+            if not has_args_section and insert_idx is not None:
+                # Need to create Args section
+                base_indent = self._get_base_indent(lines)
+
+                # Add blank line before Args section if needed
+                if insert_idx > 0 and lines[insert_idx - 1].strip():
+                    lines.insert(insert_idx, "")
+                    insert_idx += 1
+
+                # Add Args section header
+                lines.insert(insert_idx, f"{base_indent}Args:")
+                insert_idx += 1
+
+            # Get parameter documentation
+            if self.use_custom_handler and self.message_handler.__doc__:
+                # Extract parameter docs from custom handler's docstring
+                param_docs = self._extract_param_docs_from_handler()
+            else:
+                # Use default parameter docs
+                param_docs = [
+                    "message_title (str, optional): Title for status "
+                    "message to user.",
+                    "message_description (str, optional): Description for "
+                    "status message.",
+                    "message_attachment (str, optional): File path or URL to "
+                    "attach to message.",
+                ]
+
+            # Insert the parameter documentation
+            if insert_idx is not None and param_docs:
+                # Get proper indentation for parameters
+                indent = self._get_docstring_indent(lines, insert_idx)
+
+                # Insert each parameter doc with proper indentation
+                for doc in param_docs:
+                    lines.insert(insert_idx, f"{indent}{doc}")
+                    insert_idx += 1
+
+            wrapper.__doc__ = '\n'.join(lines)
+
+        return wrapper
+
+    def _find_docstring_insert_point(self, lines: List[str]) -> Optional[int]:
+        r"""Find where to insert parameters in a docstring."""
+        current_indent = ""
+
+        # First, look for existing Args section
+        for i, line in enumerate(lines):
+            if (
+                'Args:' in line
+                or 'Arguments:' in line
+                or 'Parameters:' in line
+            ):
+                current_indent = line[: len(line) - len(line.lstrip())]
+                # Find where Args section ends by looking for the last
+                # parameter
+                last_param_idx = None
+                for j in range(i + 1, len(lines)):
+                    stripped = lines[j].strip()
+                    # If it's an empty line, skip it
+                    if not stripped:
+                        continue
+                    # If it's a parameter line (has proper indentation and
+                    # content)
+                    if lines[j].startswith(current_indent + ' '):
+                        last_param_idx = j
+                    else:
+                        # Hit a line with different indentation or a new
+                        # section
+                        if last_param_idx is not None:
+                            return last_param_idx + 1
+                        else:
+                            # No parameters found, insert right after Args:
+                            return i + 1
+                # Args is the last section, return after last parameter
+                if last_param_idx is not None:
+                    return last_param_idx + 1
+                else:
+                    # No parameters found, insert right after Args:
+                    return i + 1
+
+        # No Args section, need to create one
+        # Try to insert before Returns/Yields/Raises/Examples sections
+        for i, line in enumerate(lines):
+            stripped = line.strip()
+            if any(
+                section in line
+                for section in [
+                    'Returns:',
+                    'Return:',
+                    'Yields:',
+                    'Raises:',
+                    'Examples:',
+                    'Example:',
+                    'Note:',
+                    'Notes:',
+                ]
+            ):
+                return i
+
+        # No special sections, add at the end
+        return len(lines)
+
+    def _get_docstring_indent(self, lines: List[str], insert_idx: int) -> str:
+        r"""Get the proper indentation for docstring parameters."""
+        # Look for Args: or similar section to match indentation
+        for i, line in enumerate(lines):
+            if (
+                'Args:' in line
+                or 'Arguments:' in line
+                or 'Parameters:' in line
+            ):
+                base_indent = line[: len(line) - len(line.lstrip())]
+                # Look at the next line to see parameter indentation
+                if i + 1 < len(lines):
+                    if lines[i + 1].strip():
+                        next_indent = lines[i + 1][
+                            : len(lines[i + 1]) - len(lines[i + 1].lstrip())
+                        ]
+                        if len(next_indent) > len(base_indent):
+                            return next_indent
+                return base_indent + '    '
+
+        # No Args section, use base indent + 4 spaces
+        base_indent = self._get_base_indent(lines)
+        return base_indent + '    '
+
+    def _get_base_indent(self, lines: List[str]) -> str:
+        r"""Get the base indentation level of the docstring."""
+        # Find first non-empty line to determine base indentation
+        for line in lines:
+            if line.strip() and not line.strip().startswith('"""'):
+                return line[: len(line) - len(line.lstrip())]
+        return '    '  # Default indentation
+
+    def _extract_param_docs_from_handler(self) -> List[str]:
+        r"""Extract parameter documentation from the custom handler's
+        docstring.
+        """
+        if not self.message_handler.__doc__:
+            return []
+
+        docs = []
+        handler_sig = inspect.signature(self.message_handler)
+
+        # Parse the handler's docstring to find parameter descriptions
+        lines = self.message_handler.__doc__.split('\n')
+        in_args = False
+        param_docs = {}
+
+        for line in lines:
+            if (
+                'Args:' in line
+                or 'Arguments:' in line
+                or 'Parameters:' in line
+            ):
+                in_args = True
+                continue
+            elif in_args and line.strip():
+                # Check if we've reached a new section
+                stripped_line = line.lstrip()
+                if any(
+                    section in stripped_line
+                    for section in [
+                        'Returns:',
+                        'Return:',
+                        'Yields:',
+                        'Raises:',
+                        'Examples:',
+                        'Example:',
+                        'Note:',
+                        'Notes:',
+                    ]
+                ):
+                    # End of Args section
+                    break
+            elif in_args and ':' in line:
+                # Parse parameter documentation
+                parts = line.strip().split(':', 1)
+                if len(parts) == 2:
+                    param_name = parts[0].strip()
+                    param_desc = parts[1].strip()
+                    # Extract just the parameter name (before any type
+                    # annotation)
+                    param_name = param_name.split()[0].strip()
+                    param_docs[param_name] = param_desc
+
+        # Build documentation for each parameter
+        for param_name, param in handler_sig.parameters.items():
+            if param_name != 'self':
+                # Get type annotation
+                annotation = ''
+                if param.annotation != inspect.Parameter.empty:
+                    if hasattr(param.annotation, '__name__'):
+                        annotation = f" ({param.annotation.__name__})"
+                    else:
+                        annotation = f" ({param.annotation!s})"
+
+                # Check if optional
+                optional = (
+                    ', optional'
+                    if param.default != inspect.Parameter.empty
+                    else ''
+                )
+
+                # Get description from parsed docs
+                desc = param_docs.get(
+                    param_name,
+                    f"Parameter for {self.message_handler.__name__}",
+                )
+
+                docs.append(f"{param_name}{annotation}{optional}: {desc}")
+
+        return docs