agno 2.2.13__py3-none-any.whl

agno/tools/googlesearch.py

@@ -0,0 +1,98 @@
+import json
+from typing import Any, Dict, List, Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug
+
+try:
+    from googlesearch import search
+except ImportError:
+    raise ImportError("`googlesearch-python` not installed. Please install using `pip install googlesearch-python`")
+
+try:
+    from pycountry import pycountry
+except ImportError:
+    raise ImportError("`pycountry` not installed. Please install using `pip install pycountry`")
+
+
+class GoogleSearchTools(Toolkit):
+    """
+    GoogleSearch is a Python library for searching Google easily.
+    It uses requests and BeautifulSoup4 to scrape Google.
+
+    Args:
+        fixed_max_results (Optional[int]): A fixed number of maximum results.
+        fixed_language (Optional[str]): Language of the search results.
+        headers (Optional[Any]): Custom headers for the request.
+        proxy (Optional[str]): Proxy settings for the request.
+        timeout (Optional[int]): Timeout for the request, default is 10 seconds.
+        cache_results (bool): Enable caching of search results.
+        cache_ttl (int): Time-to-live for cached results in seconds.
+        cache_dir (Optional[str]): Directory to store cache files.
+        enable_google_search (bool): Enable Google search.
+        all (bool): Enable all tools.
+    """
+
+    def __init__(
+        self,
+        fixed_max_results: Optional[int] = None,
+        fixed_language: Optional[str] = None,
+        headers: Optional[Any] = None,
+        proxy: Optional[str] = None,
+        timeout: Optional[int] = 10,
+        enable_google_search: bool = True,
+        all: bool = False,
+        **kwargs,
+    ):
+        self.fixed_max_results: Optional[int] = fixed_max_results
+        self.fixed_language: Optional[str] = fixed_language
+        self.headers: Optional[Any] = headers
+        self.proxy: Optional[str] = proxy
+        self.timeout: Optional[int] = timeout
+
+        tools = []
+        if all or enable_google_search:
+            tools.append(self.google_search)
+
+        super().__init__(name="google_search_tools", tools=tools, **kwargs)
+
+    def google_search(self, query: str, max_results: int = 5, language: str = "en") -> str:
+        """
+        Use this function to search Google for a specified query.
+
+        Args:
+            query (str): The query to search for.
+            max_results (int, optional): The maximum number of results to return. Default is 5.
+            language (str, optional): The language of the search results. Default is "en".
+
+        Returns:
+            str: A JSON formatted string containing the search results.
+        """
+        max_results = self.fixed_max_results or max_results
+        language = self.fixed_language or language
+
+        # Resolve language to ISO 639-1 code if needed
+        if len(language) != 2:
+            _language = pycountry.languages.lookup(language)
+            if _language:
+                language = _language.alpha_2
+            else:
+                language = "en"
+
+        log_debug(f"Searching Google [{language}] for: {query}")
+
+        # Perform Google search using the googlesearch-python package
+        results = list(search(query, num_results=max_results, lang=language))
+
+        # Collect the search results
+        res: List[Dict[str, str]] = []
+        for result in results:
+            res.append(
+                {
+                    "title": result.title,
+                    "url": result.url,
+                    "description": result.description,
+                }
+            )
+
+        return json.dumps(res, indent=2)

agno/tools/googlesheets.py

@@ -0,0 +1,377 @@
+"""
+Google Sheets Toolset for interacting with Sheets API
+
+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)
+
+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 Sheets API:
+   - Go to "APIs & Services" > "Enable APIs and Services"
+   - Search for "Google Sheets API"
+   - Click "Enable"
+
+4. Create OAuth 2.0 credentials:
+   - Go to "APIs & Services" > "Credentials"
+   - Click "Create Credentials" > "OAuth client ID"
+   - Go through the OAuth consent screen setup
+   - Give it a name and click "Create"
+   - 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. 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
+   ```
+
+Alternatively, follow the instructions in the Google Sheets API Quickstart guide:
+1: Steps: https://developers.google.com/sheets/api/quickstart/python
+2: Save the credentials.json file to the root of the project or update the path in the GoogleSheetsTools class
+
+Note: The first time you run the application, it will open a browser window for OAuth authentication.
+A token.json file will be created to store the authentication credentials for future use.
+"""
+
+import json
+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.oauth2.service_account import Credentials as ServiceAccountCredentials
+    from google_auth_oauthlib.flow import InstalledAppFlow
+    from googleapiclient.discovery import Resource, build
+except ImportError:
+    raise ImportError(
+        "`google-api-python-client` `google-auth-httplib2` `google-auth-oauthlib` not installed. Please install 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:
+            self.service = build("sheets", "v4", credentials=self.creds)
+        return func(self, *args, **kwargs)
+
+    return wrapper
+
+
+class GoogleSheetsTools(Toolkit):
+    # Default scopes for Google Sheets API access
+    DEFAULT_SCOPES = {
+        "read": "https://www.googleapis.com/auth/spreadsheets.readonly",
+        "write": "https://www.googleapis.com/auth/spreadsheets",
+    }
+
+    service: Optional[Resource]
+
+    def __init__(
+        self,
+        scopes: Optional[List[str]] = None,
+        spreadsheet_id: Optional[str] = None,
+        spreadsheet_range: Optional[str] = None,
+        creds: Optional[Union[Credentials, ServiceAccountCredentials]] = None,
+        creds_path: Optional[str] = None,
+        token_path: Optional[str] = None,
+        service_account_path: Optional[str] = None,
+        oauth_port: int = 0,
+        enable_read_sheet: bool = True,
+        enable_create_sheet: bool = False,
+        enable_update_sheet: bool = False,
+        enable_create_duplicate_sheet: bool = False,
+        all: bool = False,
+        **kwargs,
+    ):
+        """Initialize GoogleSheetsTools with the specified configuration.
+
+        Args:
+            scopes (Optional[List[str]]): Custom OAuth scopes. If None, uses write scope by default.
+            spreadsheet_id (Optional[str]): ID of the target spreadsheet.
+            spreadsheet_range (Optional[str]): Range within the spreadsheet.
+            creds (Optional[Credentials | ServiceAccountCredentials]): Pre-existing credentials.
+            creds_path (Optional[str]): Path to credentials file.
+            token_path (Optional[str]): Path to token file.
+            service_account_path (Optional[str]): Path to a service account file.
+            oauth_port (int): Port to use for OAuth authentication. Defaults to 0.
+            enable_read_sheet (bool): Enable reading from a sheet.
+            enable_create_sheet (bool): Enable creating a sheet.
+            enable_update_sheet (bool): Enable updating a sheet.
+            enable_create_duplicate_sheet (bool): Enable creating a duplicate sheet.
+            all (bool): Enable all tools.
+        """
+
+        self.spreadsheet_id = spreadsheet_id
+        self.spreadsheet_range = spreadsheet_range
+        self.creds = creds
+        self.credentials_path = creds_path
+        self.token_path = token_path
+        self.oauth_port = oauth_port
+        self.service: Optional[Resource] = None
+        self.service_account_path = service_account_path
+
+        # Determine required scopes based on operations if no custom scopes provided
+        if scopes is None:
+            self.scopes = []
+            if enable_read_sheet:
+                self.scopes.append(self.DEFAULT_SCOPES["read"])
+            if enable_create_sheet or enable_update_sheet or enable_create_duplicate_sheet:
+                self.scopes.append(self.DEFAULT_SCOPES["write"])
+            # Remove duplicates while preserving order
+            self.scopes = list(dict.fromkeys(self.scopes))
+        else:
+            self.scopes = scopes
+            # Validate that required scopes are present for requested operations
+            if (enable_create_sheet or enable_update_sheet or enable_create_duplicate_sheet) and self.DEFAULT_SCOPES[
+                "write"
+            ] not in self.scopes:
+                raise ValueError(f"The scope {self.DEFAULT_SCOPES['write']} is required for write operations")
+            if (
+                enable_read_sheet
+                and self.DEFAULT_SCOPES["read"] not in self.scopes
+                and self.DEFAULT_SCOPES["write"] not in self.scopes
+            ):
+                raise ValueError(
+                    f"Either {self.DEFAULT_SCOPES['read']} or {self.DEFAULT_SCOPES['write']} is required for read operations"
+                )
+
+        tools: List[Any] = []
+        if all or enable_read_sheet:
+            tools.append(self.read_sheet)
+        if all or enable_create_sheet:
+            tools.append(self.create_sheet)
+        if all or enable_update_sheet:
+            tools.append(self.update_sheet)
+        if all or enable_create_duplicate_sheet:
+            tools.append(self.create_duplicate_sheet)
+
+        super().__init__(name="google_sheets_tools", tools=tools, **kwargs)
+
+    def _auth(self) -> None:
+        """
+        Authenticate with Google Sheets API
+        """
+        if self.creds and self.creds.valid:
+            return
+
+        service_account_path = self.service_account_path or getenv("GOOGLE_SERVICE_ACCOUNT_FILE")
+
+        if service_account_path:
+            self.creds = ServiceAccountCredentials.from_service_account_file(
+                service_account_path,
+                scopes=self.scopes,
+            )
+            if self.creds and self.creds.expired:
+                self.creds.refresh(Request())
+            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:  # type: ignore
+                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.oauth_port)
+            token_file.write_text(self.creds.to_json()) if self.creds else None  # type: ignore
+
+    @authenticate
+    def read_sheet(self, spreadsheet_id: Optional[str] = None, spreadsheet_range: Optional[str] = None) -> str:
+        """
+        Read values from a Google Sheet. Prioritizes instance attributes over method parameters.
+
+        Args:
+            spreadsheet_id: Fallback spreadsheet ID if instance attribute is None
+            spreadsheet_range: Fallback range if instance attribute is None
+
+        Returns:
+            JSON of list of rows, where each row is a list of values
+        """
+        if not self.creds:
+            return "Not authenticated. Call auth() first."
+
+        # Prioritize instance attributes
+        sheet_id = self.spreadsheet_id or spreadsheet_id
+        sheet_range = self.spreadsheet_range or spreadsheet_range
+
+        if not sheet_id or not sheet_range:
+            return "Spreadsheet ID and range must be provided either in constructor or method call"
+
+        try:
+            result = self.service.spreadsheets().values().get(spreadsheetId=sheet_id, range=sheet_range).execute()  # type: ignore
+            return json.dumps(result.get("values", []))
+
+        except Exception as e:
+            return f"Error reading Google Sheet: {e}"
+
+    @authenticate
+    def create_sheet(self, title: str) -> str:
+        """
+        Create a Google Sheet with a given title.
+
+        Args:
+            title: The title of the Google Sheet
+
+        Returns:
+            The ID of the created Google Sheet
+        """
+        if not self.creds:
+            return "Not authenticated. Call auth() first."
+
+        try:
+            spreadsheet = {"properties": {"title": title}}
+
+            spreadsheet = self.service.spreadsheets().create(body=spreadsheet, fields="spreadsheetId").execute()  # type: ignore
+            spreadsheet_id = spreadsheet.get("spreadsheetId")
+
+            return f"Spreadsheet created: https://docs.google.com/spreadsheets/d/{spreadsheet_id}"
+
+        except Exception as e:
+            return f"Error creating Google Sheet: {e}"
+
+    @authenticate
+    def update_sheet(
+        self, data: List[List[Any]], spreadsheet_id: Optional[str] = None, range_name: Optional[str] = None
+    ) -> str:
+        """Updates a Google Sheet with the provided data.
+
+        Note: This function can overwrite existing data in the sheet.
+        User needs to ensure that the provided range correctly matches the data that needs to be updated.
+
+        Args:
+            data: The data to update the sheet with
+            spreadsheet_id: The ID of the Google Sheet
+            range_name: The range of the Google Sheet to update
+
+        Returns:
+            A message indicating the success or failure of the operation
+        """
+        if not self.creds:
+            return "Not authenticated. Call auth() first."
+
+        try:
+            # Define the request body
+            body = {"values": data}
+
+            # Update the sheet
+            self.service.spreadsheets().values().update(  # type: ignore
+                spreadsheetId=spreadsheet_id,
+                range=range_name,
+                valueInputOption="RAW",
+                body=body,
+            ).execute()
+
+            return f"Sheet updated successfully: {spreadsheet_id}"
+
+        except Exception as e:
+            return f"Error updating Google Sheet: {e}"
+
+    @authenticate
+    def create_duplicate_sheet(
+        self, source_id: str, new_title: Optional[str] = None, copy_permissions: bool = True
+    ) -> str:
+        """Duplicate a Google Spreadsheet using the Google Drive API's copy feature.
+        This ensures an exact duplicate including formatting and data.
+
+        Note: Make sure your credentials include the drive scope 'https://www.googleapis.com/auth/drive'
+
+        Args:
+            source_id: The ID of the source spreadsheet.
+            new_title: Optional new title for the duplicated spreadsheet. If not provided, the source title will be used.
+            copy_permissions: Whether to copy the permissions from the source spreadsheet. Defaults to True.
+
+        Returns:
+            A link to the duplicated spreadsheet.
+        """
+        if not self.creds:
+            return "Not authenticated. Call auth() first."
+
+        if not self.service:
+            return "Service not initialized"
+
+        try:
+            # Ensure the drive scope is included
+            if "https://www.googleapis.com/auth/drive" not in self.scopes:
+                self.scopes.append("https://www.googleapis.com/auth/drive")
+                self._auth()  # Re-authenticate with updated scopes
+
+            drive_service = build("drive", "v3", credentials=self.creds)
+
+            # Use new_title if provided, otherwise fetch the title from the source spreadsheet
+            if not new_title:
+                source_sheet = self.service.spreadsheets().get(spreadsheetId=source_id).execute()
+                new_title = source_sheet["properties"]["title"]
+
+            body = {"name": new_title}
+            new_file = drive_service.files().copy(fileId=source_id, body=body).execute()
+            new_spreadsheet_id = new_file.get("id")
+
+            # Copy permissions if requested
+            if copy_permissions:
+                # Get permissions from source file
+                source_permissions = (
+                    drive_service.permissions()
+                    .list(fileId=source_id, fields="permissions(emailAddress,role,type)")
+                    .execute()
+                    .get("permissions", [])
+                )
+
+                # Apply each permission to the new file
+                for permission in source_permissions:
+                    # Skip the owner permission as it can't be transferred
+                    if permission.get("role") == "owner":
+                        continue
+
+                    drive_service.permissions().create(
+                        fileId=new_spreadsheet_id,
+                        body={
+                            "role": permission.get("role"),
+                            "type": permission.get("type"),
+                            "emailAddress": permission.get("emailAddress"),
+                        },
+                    ).execute()
+
+            return f"Spreadsheet duplicated successfully: https://docs.google.com/spreadsheets/d/{new_spreadsheet_id}"
+        except Exception as e:
+            return f"Error duplicating spreadsheet via Drive API: {e}"

agno/tools/hackernews.py

@@ -0,0 +1,77 @@
+import json
+from typing import Any, List
+
+import httpx
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, logger
+
+
+class HackerNewsTools(Toolkit):
+    """
+    HackerNews is a tool for getting top stories from Hacker News.
+
+    Args:
+        enable_get_top_stories (bool): Enable getting top stories from Hacker News. Default is True.
+        enable_get_user_details (bool): Enable getting user details from Hacker News. Default is True.
+        all (bool): Enable all tools. Overrides individual flags when True. Default is False.
+    """
+
+    def __init__(
+        self, enable_get_top_stories: bool = True, enable_get_user_details: bool = True, all: bool = False, **kwargs
+    ):
+        tools: List[Any] = []
+        if all or enable_get_top_stories:
+            tools.append(self.get_top_hackernews_stories)
+        if all or enable_get_user_details:
+            tools.append(self.get_user_details)
+
+        super().__init__(name="hackers_news", tools=tools, **kwargs)
+
+    def get_top_hackernews_stories(self, num_stories: int = 10) -> str:
+        """Use this function to get top stories from Hacker News.
+
+        Args:
+            num_stories (int): Number of stories to return. Defaults to 10.
+
+        Returns:
+            str: JSON string of top stories.
+        """
+
+        log_debug(f"Getting top {num_stories} stories from Hacker News")
+        # Fetch top story IDs
+        response = httpx.get("https://hacker-news.firebaseio.com/v0/topstories.json")
+        story_ids = response.json()
+
+        # Fetch story details
+        stories = []
+        for story_id in story_ids[:num_stories]:
+            story_response = httpx.get(f"https://hacker-news.firebaseio.com/v0/item/{story_id}.json")
+            story = story_response.json()
+            story["username"] = story["by"]
+            stories.append(story)
+        return json.dumps(stories)
+
+    def get_user_details(self, username: str) -> str:
+        """Use this function to get the details of a Hacker News user using their username.
+
+        Args:
+            username (str): Username of the user to get details for.
+
+        Returns:
+            str: JSON string of the user details.
+        """
+
+        try:
+            log_debug(f"Getting details for user: {username}")
+            user = httpx.get(f"https://hacker-news.firebaseio.com/v0/user/{username}.json").json()
+            user_details = {
+                "id": user.get("user_id"),
+                "karma": user.get("karma"),
+                "about": user.get("about"),
+                "total_items_submitted": len(user.get("submitted", [])),
+            }
+            return json.dumps(user_details)
+        except Exception as e:
+            logger.exception(e)
+            return f"Error getting user details: {e}"

agno/tools/jina.py

@@ -0,0 +1,101 @@
+from os import getenv
+from typing import Any, Dict, List, Optional
+
+import httpx
+from pydantic import BaseModel, Field, HttpUrl
+
+from agno.tools import Toolkit
+from agno.utils.log import logger
+
+
+class JinaReaderToolsConfig(BaseModel):
+    api_key: Optional[str] = Field(None, description="API key for Jina Reader")
+    base_url: HttpUrl = Field("https://r.jina.ai/", description="Base URL for Jina Reader API")  # type: ignore
+    search_url: HttpUrl = Field("https://s.jina.ai/", description="Search URL for Jina Reader API")  # type: ignore
+    max_content_length: int = Field(10000, description="Maximum content length in characters")
+    timeout: Optional[int] = Field(None, description="Timeout for Jina Reader API requests")
+    search_query_content: Optional[bool] = Field(False, description="Toggle full URL content in query search result")
+
+
+class JinaReaderTools(Toolkit):
+    def __init__(
+        self,
+        api_key: Optional[str] = getenv("JINA_API_KEY"),
+        base_url: str = "https://r.jina.ai/",
+        search_url: str = "https://s.jina.ai/",
+        max_content_length: int = 10000,
+        timeout: Optional[int] = None,
+        search_query_content: bool = True,
+        enable_read_url: bool = True,
+        enable_search_query: bool = False,
+        all: bool = False,
+        **kwargs,
+    ):
+        self.api_key = api_key or getenv("JINA_API_KEY")
+        self.config: JinaReaderToolsConfig = JinaReaderToolsConfig(
+            api_key=self.api_key,
+            base_url=base_url,
+            search_url=search_url,
+            max_content_length=max_content_length,
+            timeout=timeout,
+            search_query_content=search_query_content,
+        )
+
+        tools: List[Any] = []
+        if all or enable_read_url:
+            tools.append(self.read_url)
+        if all or enable_search_query:
+            tools.append(self.search_query)
+
+        super().__init__(name="jina_reader_tools", tools=tools, **kwargs)
+
+    def read_url(self, url: str) -> str:
+        """Reads a URL and returns the truncated content using Jina Reader API."""
+        full_url = f"{self.config.base_url}{url}"
+        try:
+            response = httpx.get(full_url, headers=self._get_headers())
+            response.raise_for_status()
+            content = response.json()
+            return self._truncate_content(str(content))
+        except Exception as e:
+            error_msg = f"Error reading URL: {str(e)}"
+            logger.error(error_msg)
+            return error_msg
+
+    def search_query(self, query: str) -> str:
+        """Performs a web search using Jina Reader API and returns the truncated results."""
+        full_url = f"{self.config.search_url}"
+        headers = self._get_headers()
+        if not self.config.search_query_content:
+            headers["X-Respond-With"] = "no-content"  # to avoid returning full content in search results
+
+        body = {"q": query}
+        try:
+            response = httpx.post(full_url, headers=headers, json=body)
+            response.raise_for_status()
+            content = response.json()
+            return self._truncate_content(str(content))
+        except Exception as e:
+            error_msg = f"Error performing search: {str(e)}"
+            logger.error(error_msg)
+            return error_msg
+
+    def _get_headers(self) -> Dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "X-With-Links-Summary": "true",
+            "X-With-Images-Summary": "true",
+        }
+        if self.config.api_key:
+            headers["Authorization"] = f"Bearer {self.config.api_key}"
+        if self.config.timeout:
+            headers["X-Timeout"] = str(self.config.timeout)
+
+        return headers
+
+    def _truncate_content(self, content: str) -> str:
+        """Truncate content to the maximum allowed length."""
+        if len(content) > self.config.max_content_length:
+            truncated = content[: self.config.max_content_length]
+            return truncated + "... (content truncated)"
+        return content