camel-ai 0.2.42__py3-none-any.whl → 0.2.44__py3-none-any.whl

camel/toolkits/__init__.py

@@ -35,6 +35,7 @@ from .google_maps_toolkit import GoogleMapsToolkit
 from .code_execution import CodeExecutionToolkit
 from .github_toolkit import GithubToolkit
 from .google_scholar_toolkit import GoogleScholarToolkit
+from .google_calendar_toolkit import GoogleCalendarToolkit
 from .arxiv_toolkit import ArxivToolkit
 from .slack_toolkit import SlackToolkit
 from .whatsapp_toolkit import WhatsAppToolkit
@@ -91,6 +92,7 @@ __all__ = [
     'AskNewsToolkit',
     'AsyncAskNewsToolkit',
     'GoogleScholarToolkit',
+    'GoogleCalendarToolkit',
     'NotionToolkit',
     'ArxivToolkit',
     'HumanToolkit',

camel/toolkits/browser_toolkit.py

@@ -20,6 +20,7 @@ import random
 import re
 import shutil
 import time
+import urllib.parse
 from copy import deepcopy
 from typing import (
     TYPE_CHECKING,
@@ -546,8 +547,10 @@ class BaseBrowser:
         file_path = None
         if save_image:
             # Get url name to form a file name
-            # TODO: Use a safer way for the url name
-            url_name = self.page_url.split("/")[-1]
+            # Use urlparser for a safer extraction the url name
+            parsed_url = urllib.parse.urlparse(self.page_url)
+            url_name = os.path.basename(str(parsed_url.path)) or "index"
+
             for char in ['\\', '/', ':', '*', '?', '"', '<', '>', '|', '.']:
                 url_name = url_name.replace(char, "_")
 
@@ -673,7 +676,8 @@ class BaseBrowser:
             rects,  # type: ignore[arg-type]
         )
         if save_image:
-            url_name = self.page_url.split("/")[-1]
+            parsed_url = urllib.parse.urlparse(self.page_url)
+            url_name = os.path.basename(str(parsed_url.path)) or "index"
             for char in ['\\', '/', ':', '*', '?', '"', '<', '>', '|', '.']:
                 url_name = url_name.replace(char, "_")
             timestamp = datetime.datetime.now().strftime("%m%d%H%M%S")
@@ -1171,6 +1175,8 @@ out the information you need. Sometimes they are extremely useful.
         message = BaseMessage.make_user_message(
             role_name='user', content=observe_prompt, image_list=[img]
         )
+        # Reset the history message of web_agent.
+        self.web_agent.reset()
         resp = self.web_agent.step(message)
 
         resp_content = resp.msgs[0].content
@@ -1400,6 +1406,8 @@ Your output should be in json format, including the following fields:
 - `if_need_replan`: bool, A boolean value indicating whether the task needs to be fundamentally replanned.
 - `replanned_schema`: str, The replanned schema for the task, which should not be changed too much compared with the original one. If the task does not need to be replanned, the value should be an empty string. 
 """
+        # Reset the history message of planning_agent.
+        self.planning_agent.reset()
         resp = self.planning_agent.step(replanning_prompt)
         resp_dict = _parse_json_output(resp.msgs[0].content)
 

camel/toolkits/google_calendar_toolkit.py

@@ -0,0 +1,432 @@
+# ========= 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. =========
+# Setup guide - https://developers.google.com/calendar/api/quickstart/python
+
+import datetime
+import os
+from typing import Any, Dict, List, Optional, Union
+
+from camel.logger import get_logger
+from camel.toolkits import FunctionTool
+from camel.toolkits.base import BaseToolkit
+from camel.utils import MCPServer, api_keys_required
+
+logger = get_logger(__name__)
+
+SCOPES = ['https://www.googleapis.com/auth/calendar']
+
+
+@MCPServer()
+class GoogleCalendarToolkit(BaseToolkit):
+    r"""A class representing a toolkit for Google Calendar operations.
+
+    This class provides methods for creating events, retrieving events,
+    updating events, and deleting events from a Google Calendar.
+    """
+
+    def __init__(
+        self,
+        timeout: Optional[float] = None,
+    ):
+        r"""Initializes a new instance of the GoogleCalendarToolkit class.
+
+        Args:
+            timeout (Optional[float]): The timeout value for API requests
+                in seconds. If None, no timeout is applied.
+                (default: :obj:`None`)
+        """
+        super().__init__(timeout=timeout)
+        self.service = self._get_calendar_service()
+
+    def create_event(
+        self,
+        event_title: str,
+        start_time: str,
+        end_time: str,
+        description: str = "",
+        location: str = "",
+        attendees_email: Optional[List[str]] = None,
+        timezone: str = "UTC",
+    ) -> Dict[str, Any]:
+        r"""Creates an event in the user's primary Google Calendar.
+
+        Args:
+            event_title (str): Title of the event.
+            start_time (str): Start time in ISO format (YYYY-MM-DDTHH:MM:SS).
+            end_time (str): End time in ISO format (YYYY-MM-DDTHH:MM:SS).
+            description (str, optional): Description of the event.
+            location (str, optional): Location of the event.
+            attendees_email (List[str], optional): List of email addresses.
+                (default: :obj:`None`)
+            timezone (str, optional): Timezone for the event.
+                (default: :obj:`UTC`)
+
+        Returns:
+            dict: A dictionary containing details of the created event.
+
+        Raises:
+            ValueError: If the event creation fails.
+        """
+        try:
+            # Handle ISO format with or without timezone info
+            if 'Z' in start_time or '+' in start_time:
+                datetime.datetime.fromisoformat(
+                    start_time.replace('Z', '+00:00')
+                )
+            else:
+                datetime.datetime.strptime(start_time, "%Y-%m-%dT%H:%M:%S")
+
+            if 'Z' in end_time or '+' in end_time:
+                datetime.datetime.fromisoformat(
+                    end_time.replace('Z', '+00:00')
+                )
+            else:
+                datetime.datetime.strptime(end_time, "%Y-%m-%dT%H:%M:%S")
+        except ValueError as e:
+            error_msg = f"Time format error: {e!s}. Expected ISO "
+            "format: YYYY-MM-DDTHH:MM:SS"
+            logger.error(error_msg)
+            return {"error": error_msg}
+
+        if attendees_email is None:
+            attendees_email = []
+
+        # Verify email addresses with improved validation
+        valid_emails = []
+        import re
+
+        email_pattern = re.compile(
+            r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+        )
+
+        for email in attendees_email:
+            if email_pattern.match(email):
+                valid_emails.append(email)
+            else:
+                logger.error(f"Invalid email address: {email}")
+                return {"error": f"Invalid email address: {email}"}
+
+        event: Dict[str, Any] = {
+            'summary': event_title,
+            'location': location,
+            'description': description,
+            'start': {
+                'dateTime': start_time,
+                'timeZone': timezone,
+            },
+            'end': {
+                'dateTime': end_time,
+                'timeZone': timezone,
+            },
+        }
+
+        if valid_emails:
+            event['attendees'] = [{'email': email} for email in valid_emails]
+
+        try:
+            created_event = (
+                self.service.events()
+                .insert(calendarId='primary', body=event)
+                .execute()
+            )
+            return {
+                'Event ID': created_event.get('id'),
+                'EventTitle': created_event.get('summary'),
+                'Start Time': created_event.get('start', {}).get('dateTime'),
+                'End Time': created_event.get('end', {}).get('dateTime'),
+                'Link': created_event.get('htmlLink'),
+            }
+        except Exception as e:
+            error_msg = f"Failed to create event: {e!s}"
+            logger.error(error_msg)
+            return {"error": error_msg}
+
+    def get_events(
+        self, max_results: int = 10, time_min: Optional[str] = None
+    ) -> Union[List[Dict[str, Any]], Dict[str, Any]]:
+        r"""Retrieves upcoming events from the user's primary Google Calendar.
+
+        Args:
+            max_results (int, optional): Maximum number of events to retrieve.
+                (default: :obj:`10`)
+            time_min (str, optional): The minimum time to fetch events from.
+                If not provided, defaults to the current time.
+                (default: :obj:`None`)
+
+        Returns:
+            Union[List[Dict[str, Any]], Dict[str, Any]]: A list of
+                dictionaries, each containing details of an event, or a
+                dictionary with an error message.
+
+        Raises:
+            ValueError: If the event retrieval fails.
+        """
+        if time_min is None:
+            time_min = (
+                datetime.datetime.now(datetime.timezone.utc).isoformat() + 'Z'
+            )
+        else:
+            if not (time_min.endswith('Z')):
+                time_min = time_min + 'Z'
+
+        try:
+            events_result = (
+                self.service.events()
+                .list(
+                    calendarId='primary',
+                    timeMin=time_min,
+                    maxResults=max_results,
+                    singleEvents=True,
+                    orderBy='startTime',
+                )
+                .execute()
+            )
+
+            events = events_result.get('items', [])
+
+            result = []
+            for event in events:
+                start = event['start'].get(
+                    'dateTime', event['start'].get('date')
+                )
+                result.append(
+                    {
+                        'Event ID': event['id'],
+                        'Summary': event.get('summary', 'No Title'),
+                        'Start Time': start,
+                        'Link': event.get('htmlLink'),
+                    }
+                )
+
+            return result
+        except Exception as e:
+            logger.error(f"Failed to retrieve events: {e!s}")
+            return {"error": f"Failed to retrieve events: {e!s}"}
+
+    def update_event(
+        self,
+        event_id: str,
+        event_title: Optional[str] = None,
+        start_time: Optional[str] = None,
+        end_time: Optional[str] = None,
+        description: Optional[str] = None,
+        location: Optional[str] = None,
+        attendees_email: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        r"""Updates an existing event in the user's primary Google Calendar.
+
+        Args:
+            event_id (str): The ID of the event to update.
+            event_title (Optional[str]): New title of the event.
+                (default: :obj:`None`)
+            start_time (Optional[str]): New start time in ISO format
+                (YYYY-MM-DDTHH:MM:SSZ).
+                (default: :obj:`None`)
+            end_time (Optional[str]): New end time in ISO format
+                (YYYY-MM-DDTHH:MM:SSZ).
+                (default: :obj:`None`)
+            description (Optional[str]): New description of the event.
+                (default: :obj:`None`)
+            location (Optional[str]): New location of the event.
+                (default: :obj:`None`)
+            attendees_email (Optional[List[str]]): List of email addresses.
+                (default: :obj:`None`)
+
+        Returns:
+            Dict[str, Any]: A dictionary containing details of the updated
+                event.
+
+        Raises:
+            ValueError: If the event update fails.
+        """
+        try:
+            event = (
+                self.service.events()
+                .get(calendarId='primary', eventId=event_id)
+                .execute()
+            )
+
+            # Update fields that are provided
+            if event_title:
+                event['summary'] = event_title
+            if description:
+                event['description'] = description
+            if location:
+                event['location'] = location
+            if start_time:
+                event['start']['dateTime'] = start_time
+            if end_time:
+                event['end']['dateTime'] = end_time
+            if attendees_email:
+                event['attendees'] = [
+                    {'email': email} for email in attendees_email
+                ]
+
+            updated_event = (
+                self.service.events()
+                .update(calendarId='primary', eventId=event_id, body=event)
+                .execute()
+            )
+
+            return {
+                'Event ID': updated_event.get('id'),
+                'Summary': updated_event.get('summary'),
+                'Start Time': updated_event.get('start', {}).get('dateTime'),
+                'End Time': updated_event.get('end', {}).get('dateTime'),
+                'Link': updated_event.get('htmlLink'),
+                'Attendees': [
+                    attendee.get('email')
+                    for attendee in updated_event.get('attendees', [])
+                ],
+            }
+        except Exception:
+            raise ValueError("Failed to update event")
+
+    def delete_event(self, event_id: str) -> str:
+        r"""Deletes an event from the user's primary Google Calendar.
+
+        Args:
+            event_id (str): The ID of the event to delete.
+
+        Returns:
+            str: A message indicating the result of the deletion.
+
+        Raises:
+            ValueError: If the event deletion fails.
+        """
+        try:
+            self.service.events().delete(
+                calendarId='primary', eventId=event_id
+            ).execute()
+            return f"Event deleted successfully. Event ID: {event_id}"
+        except Exception:
+            raise ValueError("Failed to delete event")
+
+    def get_calendar_details(self) -> Dict[str, Any]:
+        r"""Retrieves details about the user's primary Google Calendar.
+
+        Returns:
+            dict: A dictionary containing details about the calendar.
+
+        Raises:
+            ValueError: If the calendar details retrieval fails.
+        """
+        try:
+            calendar = (
+                self.service.calendars().get(calendarId='primary').execute()
+            )
+            return {
+                'Calendar ID': calendar.get('id'),
+                'Summary': calendar.get('summary'),
+                'Description': calendar.get('description', 'No description'),
+                'Time Zone': calendar.get('timeZone'),
+                'Access Role': calendar.get('accessRole'),
+            }
+        except Exception:
+            raise ValueError("Failed to retrieve calendar details")
+
+    def _get_calendar_service(self):
+        r"""Authenticates and creates a Google Calendar service object.
+
+        Returns:
+            Resource: A Google Calendar API service object.
+
+        Raises:
+            ValueError: If authentication fails.
+        """
+        from google.auth.transport.requests import Request
+        from googleapiclient.discovery import build
+
+        # Get credentials through authentication
+        try:
+            creds = self._authenticate()
+
+            # Refresh token if expired
+            if creds and creds.expired and creds.refresh_token:
+                creds.refresh(Request())
+
+            service = build('calendar', 'v3', credentials=creds)
+            return service
+        except Exception as e:
+            raise ValueError(f"Failed to build service: {e!s}")
+
+    @api_keys_required(
+        [
+            (None, "GOOGLE_CLIENT_ID"),
+            (None, "GOOGLE_CLIENT_SECRET"),
+        ]
+    )
+    def _authenticate(self):
+        r"""Gets Google OAuth2 credentials from environment variables.
+
+        Environment variables needed:
+        - GOOGLE_CLIENT_ID: The OAuth client ID
+        - GOOGLE_CLIENT_SECRET: The OAuth client secret
+        - GOOGLE_REFRESH_TOKEN: (Optional) Refresh token for reauthorization
+
+        Returns:
+            Credentials: A Google OAuth2 credentials object.
+        """
+        client_id = os.environ.get('GOOGLE_CLIENT_ID')
+        client_secret = os.environ.get('GOOGLE_CLIENT_SECRET')
+        refresh_token = os.environ.get('GOOGLE_REFRESH_TOKEN')
+        token_uri = os.environ.get(
+            'GOOGLE_TOKEN_URI', 'https://oauth2.googleapis.com/token'
+        )
+
+        from google.oauth2.credentials import Credentials
+        from google_auth_oauthlib.flow import InstalledAppFlow
+
+        # For first-time authentication
+        if not refresh_token:
+            client_config = {
+                "installed": {
+                    "client_id": client_id,
+                    "client_secret": client_secret,
+                    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+                    "token_uri": token_uri,
+                    "redirect_uris": ["http://localhost"],
+                }
+            }
+
+            flow = InstalledAppFlow.from_client_config(client_config, SCOPES)
+            creds = flow.run_local_server(port=0)
+
+            return creds
+        else:
+            # If we have a refresh token, use it to get credentials
+            return Credentials(
+                None,
+                refresh_token=refresh_token,
+                token_uri=token_uri,
+                client_id=client_id,
+                client_secret=client_secret,
+                scopes=SCOPES,
+            )
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Returns a list of FunctionTool objects representing the
+        functions in the toolkit.
+
+        Returns:
+            List[FunctionTool]: A list of FunctionTool objects
+                representing the functions in the toolkit.
+        """
+        return [
+            FunctionTool(self.create_event),
+            FunctionTool(self.get_events),
+            FunctionTool(self.update_event),
+            FunctionTool(self.delete_event),
+            FunctionTool(self.get_calendar_details),
+        ]

camel/toolkits/search_toolkit.py

@@ -13,7 +13,7 @@
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import os
 import xml.etree.ElementTree as ET
-from typing import Any, Dict, List, Literal, Optional, TypeAlias, Union
+from typing import Any, Dict, List, Literal, Optional, TypeAlias, Union, cast
 
 import requests
 
@@ -947,6 +947,123 @@ class SearchToolkit(BaseToolkit):
         except Exception as e:
             return {"error": f"Bing scraping error: {e!s}"}
 
+    @api_keys_required([(None, 'EXA_API_KEY')])
+    def search_exa(
+        self,
+        query: str,
+        search_type: Literal["auto", "neural", "keyword"] = "auto",
+        category: Optional[
+            Literal[
+                "company",
+                "research paper",
+                "news",
+                "pdf",
+                "github",
+                "tweet",
+                "personal site",
+                "linkedin profile",
+                "financial report",
+            ]
+        ] = None,
+        num_results: int = 10,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
+        use_autoprompt: bool = True,
+        text: bool = False,
+    ) -> Dict[str, Any]:
+        r"""Use Exa search API to perform intelligent web search with optional
+        content extraction.
+
+        Args:
+            query (str): The search query string.
+            search_type (Literal["auto", "neural", "keyword"]): The type of
+                search to perform. "auto" automatically decides between keyword
+                and neural search. (default: :obj:`"auto"`)
+            category (Optional[Literal]): Category to focus the search on, such
+                as "research paper" or "news". (default: :obj:`None`)
+            num_results (int): Number of results to return (max 100).
+                (default: :obj:`10`)
+            include_text (Optional[List[str]]): Strings that must be present in
+                webpage text. Limited to 1 string of up to 5 words.
+                (default: :obj:`None`)
+            exclude_text (Optional[List[str]]): Strings that must not be
+                present in webpage text. Limited to 1 string of up to 5 words.
+                (default: :obj:`None`)
+            use_autoprompt (bool): Whether to use Exa's autoprompt feature to
+                enhance the query. (default: :obj:`True`)
+            text (bool): Whether to include webpage contents in results.
+                (default: :obj:`False`)
+
+        Returns:
+            Dict[str, Any]: A dict containing search results and metadata:
+                - requestId (str): Unique identifier for the request
+                - autopromptString (str): Generated autoprompt if enabled
+                - autoDate (str): Timestamp of autoprompt generation
+                - resolvedSearchType (str): The actual search type used
+                - results (List[Dict]): List of search results with metadata
+                - searchType (str): The search type that was selected
+                - costDollars (Dict): Breakdown of API costs
+        """
+        from exa_py import Exa
+
+        EXA_API_KEY = os.getenv("EXA_API_KEY")
+
+        try:
+            exa = Exa(EXA_API_KEY)
+
+            if num_results is not None and not 0 < num_results <= 100:
+                raise ValueError("num_results must be between 1 and 100")
+
+            if include_text is not None:
+                if len(include_text) > 1:
+                    raise ValueError("include_text can only contain 1 string")
+                if len(include_text[0].split()) > 5:
+                    raise ValueError(
+                        "include_text string cannot be longer than 5 words"
+                    )
+
+            if exclude_text is not None:
+                if len(exclude_text) > 1:
+                    raise ValueError("exclude_text can only contain 1 string")
+                if len(exclude_text[0].split()) > 5:
+                    raise ValueError(
+                        "exclude_text string cannot be longer than 5 words"
+                    )
+
+            # Call Exa API with direct parameters
+            if text:
+                results = cast(
+                    Dict[str, Any],
+                    exa.search_and_contents(
+                        query=query,
+                        type=search_type,
+                        category=category,
+                        num_results=num_results,
+                        include_text=include_text,
+                        exclude_text=exclude_text,
+                        use_autoprompt=use_autoprompt,
+                        text=True,
+                    ),
+                )
+            else:
+                results = cast(
+                    Dict[str, Any],
+                    exa.search(
+                        query=query,
+                        type=search_type,
+                        category=category,
+                        num_results=num_results,
+                        include_text=include_text,
+                        exclude_text=exclude_text,
+                        use_autoprompt=use_autoprompt,
+                    ),
+                )
+
+            return results
+
+        except Exception as e:
+            return {"error": f"Exa search failed: {e!s}"}
+
     def get_tools(self) -> List[FunctionTool]:
         r"""Returns a list of FunctionTool objects representing the
         functions in the toolkit.
@@ -966,4 +1083,5 @@ class SearchToolkit(BaseToolkit):
             FunctionTool(self.search_bocha),
             FunctionTool(self.search_baidu),
             FunctionTool(self.search_bing),
+            FunctionTool(self.search_exa),
         ]