agno 2.0.1__py3-none-any.whl → 2.3.0__py3-none-any.whl

agno/tools/gmail.py

@@ -124,20 +124,6 @@ class GmailTools(Toolkit):
         self.scopes = scopes or self.DEFAULT_SCOPES
         self.port = port
 
-        """ tools functions:
-         enable_get_latest_emails (bool): Enable getting latest emails.
-         enable_get_emails_from_user (bool): Enable getting emails from specific user.
-         enable_get_unread_emails (bool): Enable getting unread emails.
-         enable_get_starred_emails (bool): Enable getting starred emails.
-         enable_get_emails_by_context (bool): Enable getting emails by context.
-         enable_get_emails_by_date (bool): Enable getting emails by date.
-         enable_get_emails_by_thread (bool): Enable getting emails by thread.
-         enable_create_draft_email (bool): Enable creating draft emails.
-         enable_send_email (bool): Enable sending emails.
-         enable_send_email_reply (bool): Enable sending email replies.
-         all (bool): Enable all tools.
-        """
-
         tools: List[Any] = [
             # Reading emails
             self.get_latest_emails,
@@ -148,10 +134,18 @@ class GmailTools(Toolkit):
             self.get_emails_by_date,
             self.get_emails_by_thread,
             self.search_emails,
+            # Email management
+            self.mark_email_as_read,
+            self.mark_email_as_unread,
             # Composing emails
             self.create_draft_email,
             self.send_email,
             self.send_email_reply,
+            # Label management
+            self.list_custom_labels,
+            self.apply_label,
+            self.remove_label,
+            self.delete_custom_label,
         ]
 
         super().__init__(name="gmail_tools", tools=tools, **kwargs)
@@ -172,13 +166,20 @@ class GmailTools(Toolkit):
             "get_emails_by_date",
             "get_emails_by_thread",
             "search_emails",
+            "list_custom_labels",
         ]
+        modify_operations = ["mark_email_as_read", "mark_email_as_unread"]
         if any(read_operation in self.functions for read_operation in read_operations):
             read_scope = "https://www.googleapis.com/auth/gmail.readonly"
             write_scope = "https://www.googleapis.com/auth/gmail.modify"
             if read_scope not in self.scopes and write_scope not in self.scopes:
                 raise ValueError(f"The scope {read_scope} is required for email reading operations")
 
+        if any(modify_operation in self.functions for modify_operation in modify_operations):
+            modify_scope = "https://www.googleapis.com/auth/gmail.modify"
+            if modify_scope not in self.scopes:
+                raise ValueError(f"The scope {modify_scope} is required for email modification operations")
+
     def _auth(self) -> None:
         """Authenticate with Gmail API"""
         token_file = Path(self.token_path or "token.json")
@@ -555,6 +556,229 @@ class GmailTools(Toolkit):
         except Exception as error:
             return f"Unexpected error retrieving emails with query '{query}': {type(error).__name__}: {error}"
 
+    @authenticate
+    def mark_email_as_read(self, message_id: str) -> str:
+        """
+        Mark a specific email as read by removing the 'UNREAD' label.
+        This is crucial for long polling scenarios to prevent processing the same email multiple times.
+
+        Args:
+            message_id (str): The ID of the message to mark as read
+
+        Returns:
+            str: Success message or error description
+        """
+        try:
+            # Remove the UNREAD label to mark the email as read
+            modify_request = {"removeLabelIds": ["UNREAD"]}
+
+            self.service.users().messages().modify(userId="me", id=message_id, body=modify_request).execute()  # type: ignore
+
+            return f"Successfully marked email {message_id} as read. Labels removed: UNREAD"
+
+        except HttpError as error:
+            return f"HTTP Error marking email {message_id} as read: {error}"
+        except Exception as error:
+            return f"Error marking email {message_id} as read: {type(error).__name__}: {error}"
+
+    @authenticate
+    def mark_email_as_unread(self, message_id: str) -> str:
+        """
+        Mark a specific email as unread by adding the 'UNREAD' label.
+        This is useful for flagging emails that need attention or re-processing.
+
+        Args:
+            message_id (str): The ID of the message to mark as unread
+
+        Returns:
+            str: Success message or error description
+        """
+        try:
+            # Add the UNREAD label to mark the email as unread
+            modify_request = {"addLabelIds": ["UNREAD"]}
+
+            self.service.users().messages().modify(userId="me", id=message_id, body=modify_request).execute()  # type: ignore
+
+            return f"Successfully marked email {message_id} as unread. Labels added: UNREAD"
+
+        except HttpError as error:
+            return f"HTTP Error marking email {message_id} as unread: {error}"
+        except Exception as error:
+            return f"Error marking email {message_id} as unread: {type(error).__name__}: {error}"
+
+    @authenticate
+    def list_custom_labels(self) -> str:
+        """
+        List only user-created custom labels (filters out system labels) in a numbered format.
+
+        Returns:
+            str: A numbered list of custom labels only
+        """
+        try:
+            results = self.service.users().labels().list(userId="me").execute()  # type: ignore
+            labels = results.get("labels", [])
+
+            # Filter out only user-created labels
+            custom_labels = [label["name"] for label in labels if label.get("type") == "user"]
+
+            if not custom_labels:
+                return "No custom labels found.\nCreate labels using apply_label function!"
+
+            # Create numbered list
+            numbered_labels = [f"{i}. {name}" for i, name in enumerate(custom_labels, 1)]
+            return f"Your Custom Labels ({len(custom_labels)} total):\n\n" + "\n".join(numbered_labels)
+
+        except HttpError as e:
+            return f"Error fetching labels: {e}"
+        except Exception as e:
+            return f"Unexpected error: {type(e).__name__}: {e}"
+
+    @authenticate
+    def apply_label(self, context: str, label_name: str, count: int = 10) -> str:
+        """
+        Find emails matching a context (search query) and apply a label, creating it if necessary.
+
+        Args:
+            context (str): Gmail search query (e.g., 'is:unread category:promotions')
+            label_name (str): Name of the label to apply
+            count (int): Maximum number of emails to process
+        Returns:
+            str: Summary of labeled emails
+        """
+        try:
+            # Fetch messages matching context
+            results = self.service.users().messages().list(userId="me", q=context, maxResults=count).execute()  # type: ignore
+
+            messages = results.get("messages", [])
+            if not messages:
+                return f"No emails found matching: '{context}'"
+
+            # Check if label exists, create if not
+            labels = self.service.users().labels().list(userId="me").execute().get("labels", [])  # type: ignore
+            label_id = None
+            for label in labels:
+                if label["name"].lower() == label_name.lower():
+                    label_id = label["id"]
+                    break
+
+            if not label_id:
+                label = (
+                    self.service.users()  # type: ignore
+                    .labels()
+                    .create(
+                        userId="me",
+                        body={"name": label_name, "labelListVisibility": "labelShow", "messageListVisibility": "show"},
+                    )
+                    .execute()
+                )
+                label_id = label["id"]
+
+            # Apply label to all matching messages
+            for msg in messages:
+                self.service.users().messages().modify(  # type: ignore
+                    userId="me", id=msg["id"], body={"addLabelIds": [label_id]}
+                ).execute()  # type: ignore
+
+            return f"Applied label '{label_name}' to {len(messages)} emails matching '{context}'."
+
+        except HttpError as e:
+            return f"Error applying label '{label_name}': {e}"
+        except Exception as e:
+            return f"Unexpected error: {type(e).__name__}: {e}"
+
+    @authenticate
+    def remove_label(self, context: str, label_name: str, count: int = 10) -> str:
+        """
+        Remove a label from emails matching a context (search query).
+
+        Args:
+            context (str): Gmail search query (e.g., 'is:unread category:promotions')
+            label_name (str): Name of the label to remove
+            count (int): Maximum number of emails to process
+        Returns:
+            str: Summary of emails with label removed
+        """
+        try:
+            # Get all labels to find the target label
+            labels = self.service.users().labels().list(userId="me").execute().get("labels", [])  # type: ignore
+            label_id = None
+
+            for label in labels:
+                if label["name"].lower() == label_name.lower():
+                    label_id = label["id"]
+                    break
+
+            if not label_id:
+                return f"Label '{label_name}' not found."
+
+            # Fetch messages matching context that have this label
+            results = (
+                self.service.users()  # type: ignore
+                .messages()
+                .list(userId="me", q=f"{context} label:{label_name}", maxResults=count)
+                .execute()
+            )
+
+            messages = results.get("messages", [])
+            if not messages:
+                return f"No emails found matching: '{context}' with label '{label_name}'"
+
+            # Remove label from all matching messages
+            removed_count = 0
+            for msg in messages:
+                self.service.users().messages().modify(  # type: ignore
+                    userId="me", id=msg["id"], body={"removeLabelIds": [label_id]}
+                ).execute()  # type: ignore
+                removed_count += 1
+
+            return f"Removed label '{label_name}' from {removed_count} emails matching '{context}'."
+
+        except HttpError as e:
+            return f"Error removing label '{label_name}': {e}"
+        except Exception as e:
+            return f"Unexpected error: {type(e).__name__}: {e}"
+
+    @authenticate
+    def delete_custom_label(self, label_name: str, confirm: bool = False) -> str:
+        """
+        Delete a custom label (with safety confirmation).
+
+        Args:
+            label_name (str): Name of the label to delete
+            confirm (bool): Must be True to actually delete the label
+        Returns:
+            str: Confirmation message or warning
+        """
+        if not confirm:
+            return f"LABEL DELETION REQUIRES CONFIRMATION. This will permanently delete the label '{label_name}' from all emails. Set confirm=True to proceed."
+
+        try:
+            # Get all labels to find the target label
+            labels = self.service.users().labels().list(userId="me").execute().get("labels", [])  # type: ignore
+            target_label = None
+
+            for label in labels:
+                if label["name"].lower() == label_name.lower():
+                    target_label = label
+                    break
+
+            if not target_label:
+                return f"Label '{label_name}' not found."
+
+            # Check if it's a system label using the type field
+            if target_label.get("type") != "user":
+                return f"Cannot delete system label '{label_name}'. Only user-created labels can be deleted."
+
+            # Delete the label
+            self.service.users().labels().delete(userId="me", id=target_label["id"]).execute()  # type: ignore
+
+            return f"Successfully deleted label '{label_name}'. This label has been removed from all emails."
+
+        except HttpError as e:
+            return f"Error deleting label '{label_name}': {e}"
+        except Exception as e:
+            return f"Unexpected error: {type(e).__name__}: {e}"
+
     def _validate_email_params(self, to: str, subject: str, body: str) -> None:
         """Validate email parameters."""
         if not to:

agno/tools/google_drive.py

@@ -0,0 +1,270 @@
+"""
+Google Drive API integration for file management and sharing.
+
+
+This module provides functions to interact with Google Drive, including listing,
+uploading, and downloading files.
+It uses the Google Drive API and handles authentication via OAuth2.
+
+Required Environment Variables:
+-----------------------------
+- GOOGLE_CLIENT_ID: Google OAuth client ID
+- GOOGLE_CLIENT_SECRET: Google OAuth client secret
+- GOOGLE_PROJECT_ID: Google Cloud project ID
+- GOOGLE_REDIRECT_URI: Google OAuth redirect URI (default: http://localhost)
+- GOOGLE_CLOUD_QUOTA_PROJECT_ID: Google Cloud quota project ID
+
+How to Get These Credentials:
+---------------------------
+1. Go to Google Cloud Console (https://console.cloud.google.com)
+2. Create a new project or select an existing one
+3. Enable the Google Drive API:
+   - Go to "APIs & Services" > "Enable APIs and Services"
+   - Search for "Google Drive API"
+   - Click "Enable"
+
+4. Create OAuth 2.0 credentials:
+   - Go to "APIs & Services" > "Credentials"
+   - Click "Create Credentials" > "OAuth client ID"
+   - Enable the OAuth Consent Screen if you haven't already
+   - After enabling the Consent Screen, click on "Create Credentials" > "OAuth client ID"
+   - You'll receive:
+     * Client ID (GOOGLE_CLIENT_ID)
+     * Client Secret (GOOGLE_CLIENT_SECRET)
+   - The Project ID (GOOGLE_PROJECT_ID) is visible in the project dropdown at the top of the page
+
+5. Add auth redirect URI:
+   - Go to https://console.cloud.google.com/auth/clients
+   - Add `http://localhost:5050` as a recognized redirect URI OR with http://localhost:{PORT_NUMBER}
+
+
+6. Set up environment variables:
+   Create a .envrc file in your project root with:
+   ``
+   export GOOGLE_CLIENT_ID=your_client_id_here
+   export GOOGLE_CLIENT_SECRET=your_client_secret_here
+   export GOOGLE_PROJECT_ID=your_project_id_here
+   export GOOGLE_REDIRECT_URI=http://localhost/  # Default value
+   export GOOGLE_AUTHENTICATION_PORT=5050  # Port for OAuth redirect
+   export GOOGLE_CLOUD_QUOTA_PROJECT_ID=your_quota_project_id_here
+   ``
+
+---
+
+Remember to install the dependencies using `pip install google google-auth-oauthlib`
+
+Important Points to Note :
+1. The first time you run the application, it will open a browser window for OAuth authentication.
+2. A token.json file will be created to store the authentication credentials for future use.
+
+You can customize the authentication port by setting the `GOOGLE_AUTHENTICATION_PORT` environment variable.
+This will be used in the `run_local_server` method for OAuth authentication.
+
+"""
+
+import mimetypes
+from functools import wraps
+from os import getenv
+from pathlib import Path
+from typing import Any, List, Optional, Union
+
+from agno.tools import Toolkit
+
+try:
+    from google.auth.transport.requests import Request
+    from google.oauth2.credentials import Credentials
+    from google_auth_oauthlib.flow import InstalledAppFlow
+    from googleapiclient.discovery import Resource, build
+    from googleapiclient.http import MediaFileUpload, MediaIoBaseDownload
+except ImportError:
+    raise ImportError(
+        "Google client library for Python not found , install it using `pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib`"
+    )
+
+
+def authenticate(func):
+    """Decorator to ensure authentication before executing a function."""
+
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        if not self.creds or not self.creds.valid:
+            self._auth()
+        if not self.service:
+            # Set quota project on credentials if available
+            creds_to_use = self.creds
+            if hasattr(self, "quota_project_id") and self.quota_project_id:
+                creds_to_use = self.creds.with_quota_project(self.quota_project_id)
+            self.service = build("drive", "v3", credentials=creds_to_use)
+        return func(self, *args, **kwargs)
+
+    return wrapper
+
+
+class GoogleDriveTools(Toolkit):
+    # Default scopes for Google Drive API access
+    DEFAULT_SCOPES = ["https://www.googleapis.com/auth/drive.file", "https://www.googleapis.com/auth/drive.readonly"]
+
+    def __init__(
+        self,
+        auth_port: Optional[int] = 5050,
+        creds: Optional[Credentials] = None,
+        scopes: Optional[List[str]] = None,
+        creds_path: Optional[str] = None,
+        token_path: Optional[str] = None,
+        quota_project_id: Optional[str] = None,
+        **kwargs,
+    ):
+        self.creds: Optional[Credentials] = creds
+        self.service: Optional[Resource] = None
+        self.credentials_path = creds_path
+        self.token_path = token_path
+        self.scopes = scopes or []
+        self.scopes.extend(self.DEFAULT_SCOPES)
+
+        self.quota_project_id = quota_project_id or getenv("GOOGLE_CLOUD_QUOTA_PROJECT_ID")
+        if not self.quota_project_id:
+            raise ValueError("GOOGLE_CLOUD_QUOTA_PROJECT_ID is not set")
+
+        self.auth_port: int = int(getenv("GOOGLE_AUTH_PORT", str(auth_port)))
+        if not self.auth_port:
+            raise ValueError("GOOGLE_AUTH_PORT is not set")
+
+        tools: List[Any] = [
+            self.list_files,
+        ]
+        super().__init__(name="google_drive_tools", tools=tools, **kwargs)
+        if not self.scopes:
+            # Add read permission by default
+            self.scopes.append(self.DEFAULT_SCOPES[1])  # 'drive.readonly'
+            # Add write permission if allow_update is True
+            if getattr(self, "allow_update", False):
+                self.scopes.append(self.DEFAULT_SCOPES[0])  # 'drive.file'
+
+    def _auth(self):
+        """
+        Authenticate and set up the Google Drive API client.
+        This method checks if credentials are valid and refreshes or requests them if needed.
+        """
+        if self.creds and self.creds.valid:
+            # Already authenticated
+            return
+
+        token_file = Path(self.token_path or "token.json")
+        creds_file = Path(self.credentials_path or "credentials.json")
+
+        if token_file.exists():
+            self.creds = Credentials.from_authorized_user_file(str(token_file), self.scopes)
+        if not self.creds or not self.creds.valid:
+            if self.creds and self.creds.expired and self.creds.refresh_token:
+                self.creds.refresh(Request())
+            else:
+                client_config = {
+                    "installed": {
+                        "client_id": getenv("GOOGLE_CLIENT_ID"),
+                        "client_secret": getenv("GOOGLE_CLIENT_SECRET"),
+                        "project_id": getenv("GOOGLE_PROJECT_ID"),
+                        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+                        "token_uri": "https://oauth2.googleapis.com/token",
+                        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+                        "redirect_uris": [getenv("GOOGLE_REDIRECT_URI", "http://localhost")],
+                    }
+                }
+                # File based authentication
+                if creds_file.exists():
+                    flow = InstalledAppFlow.from_client_secrets_file(str(creds_file), self.scopes)
+                else:
+                    flow = InstalledAppFlow.from_client_config(client_config, self.scopes)
+                # Opens up a browser window for OAuth authentication
+                self.creds = flow.run_local_server(port=self.auth_port)  # type: ignore
+
+            token_file.write_text(self.creds.to_json()) if self.creds else None
+
+    @authenticate
+    def list_files(self, query: Optional[str] = None, page_size: int = 10) -> List[dict]:
+        """
+        List files in your Google Drive.
+
+        Args:
+            query (Optional[str]): Optional search query to filter files (see Google Drive API docs).
+            page_size (int): Maximum number of files to return.
+
+        Returns:
+            List[dict]: List of file metadata dictionaries.
+        """
+        if not self.service:
+            raise ValueError("Google Drive service is not initialized. Please authenticate first.")
+        try:
+            results = (
+                self.service.files()  # type: ignore
+                .list(q=query, pageSize=page_size, fields="nextPageToken, files(id, name, mimeType, modifiedTime)")
+                .execute()
+            )
+            items = results.get("files", [])
+            return items
+        except Exception as error:
+            print(f"Could not list files: {error}")
+            return []
+
+    @authenticate
+    def upload_file(self, file_path: Union[str, Path], mime_type: Optional[str] = None) -> Optional[dict]:
+        """
+        Upload a file to your Google Drive.
+
+        Args:
+            file_path (Union[str, Path]): Path to the file you want to upload.
+            mime_type (Optional[str]): MIME type of the file. If not provided, it will be guessed.
+
+        Returns:
+            Optional[dict]: Metadata of the uploaded file, or None if upload failed.
+        """
+        if not self.service:
+            raise ValueError("Google Drive service is not initialized. Please authenticate first.")
+        file_path = Path(file_path)
+        if not file_path.exists() or not file_path.is_file():
+            raise ValueError(f"The file '{file_path}' does not exist or is not a file.")
+        if mime_type is None:
+            mime_type, _ = mimetypes.guess_type(file_path.as_posix())
+            if mime_type is None:
+                mime_type = "application/octet-stream"  # Default MIME type
+
+        file_metadata = {"name": file_path.name}
+        media = MediaFileUpload(file_path.as_posix(), mimetype=mime_type)
+
+        try:
+            uploaded_file = (
+                self.service.files()  # type: ignore
+                .create(body=file_metadata, media_body=media, fields="id, name, mimeType, modifiedTime")
+                .execute()
+            )
+            return uploaded_file
+        except Exception as error:
+            print(f"Could not upload file '{file_path}': {error}")
+            return None
+
+    @authenticate
+    def download_file(self, file_id: str, dest_path: Union[str, Path]) -> Optional[Path]:
+        """
+        Download a file from your Google Drive.
+
+        Args:
+            file_id (str): The ID of the file you want to download.
+            dest_path (Union[str, Path]): Where to save the downloaded file.
+
+        Returns:
+            Optional[Path]: The path to the downloaded file, or None if download failed.
+        """
+        if not self.service:
+            raise ValueError("Google Drive service is not initialized. Please authenticate first.")
+        dest_path = Path(dest_path)
+        try:
+            request = self.service.files().get_media(fileId=file_id)  # type: ignore
+            with open(dest_path, "wb") as fh:
+                downloader = MediaIoBaseDownload(fh, request)
+                done = False
+                while not done:
+                    status, done = downloader.next_chunk()
+                    print(f"Download progress: {int(status.progress() * 100)}%.")
+            return dest_path
+        except Exception as error:
+            print(f"Could not download file '{file_id}': {error}")
+            return None