agno 0.1.2__py3-none-any.whl → 2.3.13__py3-none-any.whl

agno/tools/google_bigquery.py

@@ -0,0 +1,117 @@
+import json
+from os import getenv
+from typing import Any, List, Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, logger
+
+try:
+    from google.cloud import bigquery
+except ImportError:
+    raise ImportError("`bigquery` not installed. Please install using `pip install google-cloud-bigquery`")
+
+
+class GoogleBigQueryTools(Toolkit):
+    def __init__(
+        self,
+        dataset: str,
+        project: Optional[str] = None,
+        location: Optional[str] = None,
+        credentials: Optional[Any] = None,
+        enable_list_tables: bool = True,
+        enable_describe_table: bool = True,
+        enable_run_sql_query: bool = True,
+        all: bool = False,
+        **kwargs,
+    ):
+        self.project = project or getenv("GOOGLE_CLOUD_PROJECT")
+        self.location = location or getenv("GOOGLE_CLOUD_LOCATION")
+
+        if not self.project:
+            raise ValueError("project is required")
+        if not self.location:
+            raise ValueError("location is required")
+
+        self.dataset = dataset
+
+        # Initialize the BQ CLient
+        self.client = bigquery.Client(project=self.project, credentials=credentials)
+
+        tools: List[Any] = []
+        if all or enable_list_tables:
+            tools.append(self.list_tables)
+        if all or enable_describe_table:
+            tools.append(self.describe_table)
+        if all or enable_run_sql_query:
+            tools.append(self.run_sql_query)
+
+        super().__init__(name="google_bigquery_tools", tools=tools, **kwargs)
+
+    def list_tables(self) -> str:
+        """Use this function to get a list of table names in the dataset.
+        Returns:
+            str: list of tables in the dataset.
+        """
+        try:
+            log_debug("listing tables in the database")
+            tables = self.client.list_tables(self.dataset)
+            tables_str = str([table.table_id for table in tables])
+            log_debug(f"table_names: {tables_str}")
+            return tables_str
+        except Exception as e:
+            logger.error(f"Error getting tables: {e}")
+            return f"Error getting tables: {e}"
+
+    def describe_table(self, table_id: str) -> str:
+        """Use this function to describe a table.
+        Args:
+            table_name (str): The name of the table to get the schema for.
+        Returns:
+            str: schema of a table
+        """
+        try:
+            table_id = f"{self.project}.{self.dataset}.{table_id}"
+            log_debug(f"Describing table: {table_id}")
+            api_response = self.client.get_table(table_id)
+            table_api_repr = api_response.to_api_repr()
+            desc = str(table_api_repr.get("description", ""))
+            col_names = str([column["name"] for column in table_api_repr["schema"]["fields"]])  # Columns in a table
+            result = json.dumps({"table_description": desc, "columns": col_names})
+            return result
+        except Exception as e:
+            logger.error(f"Error getting table schema: {e}")
+            return f"Error getting table schema: {e}"
+
+    def run_sql_query(self, query: str) -> str:
+        """Use this function to run a BigQuery SQL query and return the result.
+        Args:
+            query (str): The query to run.
+        Returns:
+            str: Result of the Google BigQuery SQL query.
+        Notes:
+            - The result may be empty if the query does not return any data.
+        """
+        try:
+            return json.dumps(self._run_sql(sql=query), default=str)
+        except Exception as e:
+            logger.error(f"Error running query: {e}")
+            return f"Error running query: {e}"
+
+    def _run_sql(self, sql: str) -> str:
+        """Internal function to run a sql query.
+        Args:
+            sql (str): The sql query to run.
+        Returns:
+            results (str): The result of the query.
+        """
+        try:
+            log_debug(f"Running Google SQL |\n{sql}")
+            cleaned_query = sql.replace("\\n", " ").replace("\n", "").replace("\\", "")
+            job_config = bigquery.QueryJobConfig(default_dataset=f"{self.project}.{self.dataset}")
+            query_job = self.client.query(cleaned_query, job_config)
+            results = query_job.result()
+            results_str = str([dict(row) for row in results])
+            return results_str.replace("\\", "").replace("\n", "")
+        except Exception as e:
+            logger.error(f"Error while executing SQL: {e}")
+            return ""

agno/tools/google_drive.py

@@ -0,0 +1,271 @@
+"""
+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
+from agno.utils.log import log_error
+
+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:
+            log_error(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:
+            log_error(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:
+            log_error(f"Could not download file '{file_id}': {error}")
+            return None

agno/tools/google_maps.py

@@ -0,0 +1,253 @@
+"""
+This module provides tools for searching business information using the Google Maps API.
+
+Prerequisites:
+- Set the environment variable `GOOGLE_MAPS_API_KEY` with your Google Maps API key.
+  You can obtain the API key from the Google Cloud Console:
+  https://console.cloud.google.com/projectselector2/google/maps-apis/credentials
+
+- You also need to activate the Address Validation API for your project.
+  https://console.developers.google.com/apis/api/addressvalidation.googleapis.com
+
+"""
+
+import json
+from datetime import datetime
+from os import getenv
+from typing import Any, List, Optional
+
+from agno.tools import Toolkit
+
+try:
+    import googlemaps
+    from google.maps import places_v1
+except ImportError:
+    print("Error importing googlemaps. Please install the package using `pip install googlemaps google-maps-places`.")
+
+
+class GoogleMapTools(Toolkit):
+    def __init__(
+        self,
+        key: Optional[str] = None,
+        **kwargs,
+    ):
+        self.api_key = key or getenv("GOOGLE_MAPS_API_KEY")
+        if not self.api_key:
+            raise ValueError("GOOGLE_MAPS_API_KEY is not set in the environment variables.")
+        self.client = googlemaps.Client(key=self.api_key)
+
+        self.places_client = places_v1.PlacesClient()
+
+        tools: List[Any] = [
+            self.search_places,
+            self.get_directions,
+            self.validate_address,
+            self.geocode_address,
+            self.reverse_geocode,
+            self.get_distance_matrix,
+            self.get_elevation,
+            self.get_timezone,
+        ]
+
+        super().__init__(name="google_maps", tools=tools, **kwargs)
+
+    def search_places(self, query: str) -> str:
+        """
+        Search for places using Google Maps Places API.
+        This tool takes a search query and returns detailed place information.
+
+        Args:
+            query (str): The query string to search for using Google Maps Search API. (e.g., "dental clinics in Noida")
+
+        Returns:
+            Stringified list of dictionaries containing business information like name, address, phone, website, rating, and reviews etc.
+        """
+        try:
+            # Perform places search
+            request = places_v1.SearchTextRequest(
+                text_query=query,
+            )
+            response = self.places_client.search_text(request=request, metadata=[("x-goog-fieldmask", "*")])
+
+            places = []
+            for place in response.places:
+                place_info = {
+                    "name": place.display_name.text,
+                    "address": place.formatted_address,
+                    "rating": place.rating,
+                    "reviews": [{"text": review.text.text, "rating": review.rating} for review in place.reviews],
+                    "place_id": place.id,
+                    "phone": place.international_phone_number,
+                    "website": place.website_uri,
+                    "hours": [description for description in place.regular_opening_hours.weekday_descriptions],
+                }
+
+                places.append(place_info)
+
+            return json.dumps(places)
+
+        except Exception as e:
+            print(f"Error searching Google Maps: {str(e)}")
+            return str([])
+
+    def get_directions(
+        self,
+        origin: str,
+        destination: str,
+        mode: str = "driving",
+        departure_time: Optional[datetime] = None,
+        avoid: Optional[List[str]] = None,
+    ) -> str:
+        """
+        Get directions between two locations using Google Maps Directions API.
+
+        Args:
+            origin (str): Starting point address or coordinates
+            destination (str): Destination address or coordinates
+            mode (str, optional): Travel mode. Options: "driving", "walking", "bicycling", "transit". Defaults to "driving"
+            departure_time (datetime, optional): Desired departure time for transit directions
+            avoid (List[str], optional): Features to avoid: "tolls", "highways", "ferries"
+
+        Returns:
+            str: Stringified dictionary containing route information including steps, distance, duration, etc.
+        """
+        try:
+            result = self.client.directions(origin, destination, mode=mode, departure_time=departure_time, avoid=avoid)
+            return str(result)
+        except Exception as e:
+            print(f"Error getting directions: {str(e)}")
+            return str([])
+
+    def validate_address(
+        self, address: str, region_code: str = "US", locality: Optional[str] = None, enable_usps_cass: bool = False
+    ) -> str:
+        """
+        Validate an address using Google Maps Address Validation API.
+
+        Args:
+            address (str): The address to validate
+            region_code (str): The region code (e.g., "US" for United States)
+            locality (str, optional): The locality (city) to help with validation
+            enable_usps_cass (bool): Whether to enable USPS CASS validation for US addresses
+
+        Returns:
+            str: Stringified dictionary containing address validation results
+        """
+        try:
+            result = self.client.addressvalidation(
+                [address], regionCode=region_code, locality=locality, enableUspsCass=enable_usps_cass
+            )
+            return str(result)
+        except Exception as e:
+            print(f"Error validating address: {str(e)}")
+            return str({})
+
+    def geocode_address(self, address: str, region: Optional[str] = None) -> str:
+        """
+        Convert an address into geographic coordinates using Google Maps Geocoding API.
+
+        Args:
+            address (str): The address to geocode
+            region (str, optional): The region code to bias results
+
+        Returns:
+            str: Stringified list of dictionaries containing location information
+        """
+        try:
+            result = self.client.geocode(address, region=region)
+            return str(result)
+        except Exception as e:
+            print(f"Error geocoding address: {str(e)}")
+            return str([])
+
+    def reverse_geocode(
+        self, lat: float, lng: float, result_type: Optional[List[str]] = None, location_type: Optional[List[str]] = None
+    ) -> str:
+        """
+        Convert geographic coordinates into an address using Google Maps Reverse Geocoding API.
+
+        Args:
+            lat (float): Latitude
+            lng (float): Longitude
+            result_type (List[str], optional): Array of address types to filter results
+            location_type (List[str], optional): Array of location types to filter results
+
+        Returns:
+            str: Stringified list of dictionaries containing address information
+        """
+        try:
+            result = self.client.reverse_geocode((lat, lng), result_type=result_type, location_type=location_type)
+            return str(result)
+        except Exception as e:
+            print(f"Error reverse geocoding: {str(e)}")
+            return str([])
+
+    def get_distance_matrix(
+        self,
+        origins: List[str],
+        destinations: List[str],
+        mode: str = "driving",
+        departure_time: Optional[datetime] = None,
+        avoid: Optional[List[str]] = None,
+    ) -> str:
+        """
+        Calculate distance and time for a matrix of origins and destinations.
+
+        Args:
+            origins (List[str]): List of addresses or coordinates
+            destinations (List[str]): List of addresses or coordinates
+            mode (str, optional): Travel mode. Options: "driving", "walking", "bicycling", "transit"
+            departure_time (datetime, optional): Desired departure time
+            avoid (List[str], optional): Features to avoid: "tolls", "highways", "ferries"
+
+        Returns:
+            str: Stringified dictionary containing distance and duration information
+        """
+        try:
+            result = self.client.distance_matrix(
+                origins, destinations, mode=mode, departure_time=departure_time, avoid=avoid
+            )
+            return str(result)
+        except Exception as e:
+            print(f"Error getting distance matrix: {str(e)}")
+            return str({})
+
+    def get_elevation(self, lat: float, lng: float) -> str:
+        """
+        Get the elevation for a specific location using Google Maps Elevation API.
+
+        Args:
+            lat (float): Latitude
+            lng (float): Longitude
+
+        Returns:
+            str: Stringified dictionary containing elevation data
+        """
+        try:
+            result = self.client.elevation((lat, lng))
+            return str(result)
+        except Exception as e:
+            print(f"Error getting elevation: {str(e)}")
+            return str([])
+
+    def get_timezone(self, lat: float, lng: float, timestamp: Optional[datetime] = None) -> str:
+        """
+        Get timezone information for a location using Google Maps Time Zone API.
+
+        Args:
+            lat (float): Latitude
+            lng (float): Longitude
+            timestamp (datetime, optional): The timestamp to use for timezone calculation
+
+        Returns:
+            str: Stringified dictionary containing timezone information
+        """
+        try:
+            if timestamp is None:
+                timestamp = datetime.now()
+
+            result = self.client.timezone(location=(lat, lng), timestamp=timestamp)
+            return str(result)
+        except Exception as e:
+            print(f"Error getting timezone: {str(e)}")
+            return str({})