agno 2.2.13__py3-none-any.whl

agno/tools/brandfetch.py

@@ -0,0 +1,213 @@
+"""
+Going to contribute this to agno toolkits.
+"""
+
+from os import getenv
+from typing import Any, Optional
+
+try:
+    import httpx
+except ImportError:
+    raise ImportError("`httpx` not installed.")
+
+from agno.tools import Toolkit
+
+
+class BrandfetchTools(Toolkit):
+    """
+    Brandfetch API toolkit for retrieving brand data and searching brands.
+
+    Supports both Brand API (retrieve comprehensive brand data) and
+    Brand Search API (find and search brands by name).
+
+    -- Brand API
+
+    api_key: str - your Brandfetch API key
+
+    -- Brand Search API
+
+    client_id: str - your Brandfetch Client ID
+
+    all: bool - if True, will use all tools
+    enable_search_by_identifier: bool - if True, will use search by identifier
+    enable_search_by_brand: bool - if True, will use search by brand
+    enable_asearch_by_identifier: bool - if True, will use async search by identifier
+    enable_asearch_by_brand: bool - if True, will use async search by brand
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        client_id: Optional[str] = None,
+        base_url: str = "https://api.brandfetch.io/v2",
+        timeout: Optional[float] = 20.0,
+        enable_search_by_identifier: bool = True,
+        enable_search_by_brand: bool = False,
+        all: bool = False,
+        async_tools: bool = False,
+        **kwargs,
+    ):
+        self.api_key = api_key or getenv("BRANDFETCH_API_KEY")
+        self.client_id = client_id or getenv("BRANDFETCH_CLIENT_ID")
+        self.base_url = base_url
+        self.timeout = httpx.Timeout(timeout)
+        self.search_url = f"{self.base_url}/search"
+        self.brand_url = f"{self.base_url}/brands"
+
+        tools: list[Any] = []
+        # Backward-compat mapping: prefer new enable_* flags, but honor legacy toggles
+        if async_tools:
+            if all or enable_search_by_identifier:
+                tools.append(self.asearch_by_identifier)
+            if all or enable_search_by_brand:
+                tools.append(self.asearch_by_brand)
+        else:
+            if all or enable_search_by_identifier:
+                tools.append(self.search_by_identifier)
+            if all or enable_search_by_brand:
+                tools.append(self.search_by_brand)
+        name = kwargs.pop("name", "brandfetch_tools")
+        super().__init__(name=name, tools=tools, **kwargs)
+
+    async def asearch_by_identifier(self, identifier: str) -> dict[str, Any]:
+        """
+        Search for brand data by identifier (domain, brand id, isin, stock ticker).
+
+        Args:
+            identifier: Options are you can use: Domain (nike.com), Brand ID (id_0dwKPKT), ISIN (US6541061031), Stock Ticker (NKE)
+        Returns:
+            Dict containing brand data including logos, colors, fonts, and other brand assets
+
+        Raises:
+            ValueError: If no API key is provided
+        """
+        if not self.api_key:
+            raise ValueError("API key is required for brand search by identifier")
+
+        url = f"{self.brand_url}/{identifier}"
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.get(url, headers=headers)
+                response.raise_for_status()
+                return response.json()
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return {"error": f"Brand not found for identifier: {identifier}"}
+            elif e.response.status_code == 401:
+                return {"error": "Invalid API key"}
+            elif e.response.status_code == 429:
+                return {"error": "Rate limit exceeded"}
+            else:
+                return {"error": f"API error: {e.response.status_code}"}
+        except httpx.RequestError as e:
+            return {"error": f"Request failed: {str(e)}"}
+
+    def search_by_identifier(self, identifier: str) -> dict[str, Any]:
+        """
+        Search for brand data by identifier (domain, brand id, isin, stock ticker).
+
+        Args:
+            identifier: Options are you can use: Domain (nike.com), Brand ID (id_0dwKPKT), ISIN (US6541061031), Stock Ticker (NKE)
+
+        Returns:
+            Dict containing brand data including logos, colors, fonts, and other brand assets
+
+        Raises:
+            ValueError: If no API key is provided
+        """
+        if not self.api_key:
+            raise ValueError("API key is required for brand search by identifier")
+
+        url = f"{self.brand_url}/{identifier}"
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.get(url, headers=headers)
+                response.raise_for_status()
+                return response.json()
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return {"error": f"Brand not found for identifier: {identifier}"}
+            elif e.response.status_code == 401:
+                return {"error": "Invalid API key"}
+            elif e.response.status_code == 429:
+                return {"error": "Rate limit exceeded"}
+            else:
+                return {"error": f"API error: {e.response.status_code}"}
+        except httpx.RequestError as e:
+            return {"error": f"Request failed: {str(e)}"}
+
+    async def asearch_by_brand(self, name: str) -> dict[str, Any]:
+        """
+        Search for brands by name using the Brand Search API - can give you the right brand id to use for the brand api.
+
+        Args:
+            name: Brand name to search for (e.g., 'Google', 'Apple')
+
+        Returns:
+            Dict containing search results with brand matches
+
+        Raises:
+            ValueError: If no client ID is provided
+        """
+        if not self.client_id:
+            raise ValueError("Client ID is required for brand search by name")
+
+        url = f"{self.search_url}/{name}"
+        params = {"c": self.client_id}
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.get(url, params=params)
+                response.raise_for_status()
+                return response.json()
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return {"error": f"No brands found for name: {name}"}
+            elif e.response.status_code == 401:
+                return {"error": "Invalid client ID"}
+            elif e.response.status_code == 429:
+                return {"error": "Rate limit exceeded"}
+            else:
+                return {"error": f"API error: {e.response.status_code}"}
+        except httpx.RequestError as e:
+            return {"error": f"Request failed: {str(e)}"}
+
+    def search_by_brand(self, name: str) -> dict[str, Any]:
+        """
+        Search for brands by name using the Brand Search API - can give you the right brand id to use for the brand api.
+
+        Args:
+            name: Brand name to search for (e.g., 'Google', 'Apple')
+
+        Returns:
+            Dict containing search results with brand matches
+
+        Raises:
+            ValueError: If no client ID is provided
+        """
+        if not self.client_id:
+            raise ValueError("Client ID is required for brand search by name")
+
+        url = f"{self.search_url}/{name}"
+        params = {"c": self.client_id}
+
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.get(url, params=params)
+                response.raise_for_status()
+                return response.json()
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return {"error": f"No brands found for name: {name}"}
+            elif e.response.status_code == 401:
+                return {"error": "Invalid client ID"}
+            elif e.response.status_code == 429:
+                return {"error": "Rate limit exceeded"}
+            else:
+                return {"error": f"API error: {e.response.status_code}"}
+        except httpx.RequestError as e:
+            return {"error": f"Request failed: {str(e)}"}

agno/tools/bravesearch.py

@@ -0,0 +1,106 @@
+import json
+from os import getenv
+from typing import Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import log_info
+
+try:
+    from brave import Brave
+except ImportError:
+    raise ImportError("`brave-search` not installed. Please install using `pip install brave-search`")
+
+
+class BraveSearchTools(Toolkit):
+    """
+    BraveSearch is a toolkit for searching Brave easily.
+
+    Args:
+        api_key (str, optional): Brave API key. If not provided, will use BRAVE_API_KEY environment variable.
+        fixed_max_results (Optional[int]): A fixed number of maximum results.
+        fixed_language (Optional[str]): A fixed language for the search results.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        fixed_max_results: Optional[int] = None,
+        fixed_language: Optional[str] = None,
+        enable_brave_search: bool = True,
+        all: bool = False,
+        **kwargs,
+    ):
+        self.api_key = api_key or getenv("BRAVE_API_KEY")
+        if not self.api_key:
+            raise ValueError("BRAVE_API_KEY is required. Please set the BRAVE_API_KEY environment variable.")
+
+        self.fixed_max_results = fixed_max_results
+        self.fixed_language = fixed_language
+
+        self.brave_client = Brave(api_key=self.api_key)
+
+        tools = []
+        if all or enable_brave_search:
+            tools.append(self.brave_search)
+
+        super().__init__(
+            name="brave_search",
+            tools=tools,
+            **kwargs,
+        )
+
+    def brave_search(
+        self,
+        query: str,
+        max_results: int = 5,
+        country: str = "US",
+        search_lang: str = "en",
+    ) -> str:
+        """
+        Search Brave for the specified query and return the results.
+
+        Args:
+            query (str): The query to search for.
+            max_results (int, optional): The maximum number of results to return. Default is 5.
+            country (str, optional): The country code for search results. Default is "US".
+            search_lang (str, optional): The language of the search results. Default is "en".
+        Returns:
+            str: A JSON formatted string containing the search results.
+        """
+        final_max_results = self.fixed_max_results if self.fixed_max_results is not None else max_results
+        final_search_lang = self.fixed_language if self.fixed_language is not None else search_lang
+
+        if not query:
+            return json.dumps({"error": "Please provide a query to search for"})
+
+        log_info(f"Searching Brave for: {query}")
+
+        search_params = {
+            "q": query,
+            "count": final_max_results,
+            "country": country,
+            "search_lang": final_search_lang,
+            "result_filter": "web",
+        }
+
+        search_results = self.brave_client.search(**search_params)
+
+        filtered_results = {
+            "web_results": [],
+            "query": query,
+            "total_results": 0,
+        }
+
+        if hasattr(search_results, "web") and search_results.web:
+            web_results = []
+            for result in search_results.web.results:
+                web_result = {
+                    "title": result.title,
+                    "url": str(result.url),
+                    "description": result.description,
+                }
+                web_results.append(web_result)
+            filtered_results["web_results"] = web_results
+            filtered_results["total_results"] = len(web_results)
+
+        return json.dumps(filtered_results, indent=2)

agno/tools/brightdata.py

@@ -0,0 +1,367 @@
+import base64
+import json
+from os import getenv
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+from agno.agent import Agent
+from agno.media import Image
+from agno.tools import Toolkit
+from agno.tools.function import ToolResult
+from agno.utils.log import log_debug, log_error, log_info
+
+try:
+    import requests
+except ImportError:
+    raise ImportError("`requests` not installed.")
+
+
+class BrightDataTools(Toolkit):
+    """
+    BrightData is a toolkit for web scraping, screenshots, search engines, and web data feeds.
+
+    Args:
+        api_key (Optional[str]): Bright Data API key. Retrieved from BRIGHT_DATA_API_KEY env variable if not provided.
+        enable_scrape_markdown (bool): Enable webpage scraping as Markdown. Default is True.
+        enable_screenshot (bool): Enable website screenshot capture. Default is True.
+        enable_search_engine (bool): Enable search engine functionality. Default is True.
+        enable_web_data_feed (bool): Enable web data feed retrieval. Default is True.
+        all (bool): Enable all tools. Overrides individual flags when True. Default is False.
+        serp_zone (str): SERP zone for search operations. Default is "serp_api".
+        web_unlocker_zone (str): Web unlocker zone for scraping operations. Default is "web_unlocker1".
+        verbose (bool): Enable verbose logging. Default is False.
+        timeout (int): Timeout in seconds for operations. Default is 600.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        enable_scrape_markdown: bool = True,
+        enable_screenshot: bool = True,
+        enable_search_engine: bool = True,
+        enable_web_data_feed: bool = True,
+        all: bool = False,
+        serp_zone: str = "serp_api",
+        web_unlocker_zone: str = "web_unlocker1",
+        verbose: bool = False,
+        timeout: int = 600,
+        **kwargs,
+    ):
+        self.api_key = api_key or getenv("BRIGHT_DATA_API_KEY")
+        if not self.api_key:
+            log_error("No Bright Data API key provided")
+            raise ValueError(
+                "No Bright Data API key provided. Please provide an api_key or set the BRIGHT_DATA_API_KEY environment variable."
+            )
+
+        self.verbose = verbose
+        self.endpoint = "https://api.brightdata.com/request"
+        self.headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+        }
+        self.web_unlocker_zone = getenv("BRIGHT_DATA_WEB_UNLOCKER_ZONE", web_unlocker_zone)
+        self.serp_zone = getenv("BRIGHT_DATA_SERP_ZONE", serp_zone)
+        self.timeout = timeout
+
+        tools: List[Any] = []
+        if all or enable_scrape_markdown:
+            tools.append(self.scrape_as_markdown)
+        if all or enable_screenshot:
+            tools.append(self.get_screenshot)
+        if all or enable_search_engine:
+            tools.append(self.search_engine)
+        if all or enable_web_data_feed:
+            tools.append(self.web_data_feed)
+
+        super().__init__(name="brightdata_tools", tools=tools, **kwargs)
+
+    def _make_request(self, payload: Dict) -> str:
+        """Make a request to Bright Data API."""
+        try:
+            if self.verbose:
+                log_info(f"[Bright Data] Request: {payload['url']}")
+
+            response = requests.post(self.endpoint, headers=self.headers, data=json.dumps(payload))
+
+            if response.status_code != 200:
+                raise Exception(f"Failed to scrape: {response.status_code} - {response.text}")
+
+            return response.text
+        except Exception as e:
+            raise Exception(f"Request failed: {e}")
+
+    def scrape_as_markdown(self, url: str) -> str:
+        """
+        Scrape a webpage and return content in Markdown format.
+
+        Args:
+            url (str): URL to scrape
+
+        Returns:
+            str: Scraped content as Markdown
+        """
+        try:
+            if not self.api_key:
+                return "Please provide a Bright Data API key"
+            if not url:
+                return "Please provide a URL to scrape"
+
+            log_info(f"Scraping URL as Markdown: {url}")
+
+            payload = {
+                "url": url,
+                "zone": self.web_unlocker_zone,
+                "format": "raw",
+                "data_format": "markdown",
+            }
+
+            content = self._make_request(payload)
+            return content
+        except Exception as e:
+            return f"Error scraping URL {url}: {e}"
+
+    def get_screenshot(self, agent: Agent, url: str, output_path: str = "screenshot.png") -> ToolResult:
+        """
+        Capture a screenshot of a webpage
+
+        Args:
+            url (str): URL to screenshot
+            output_path (str): Output path for the screenshot (not used, kept for compatibility)
+
+        Returns:
+            ToolResult: Contains the screenshot image or error message.
+        """
+        try:
+            if not self.api_key:
+                return ToolResult(content="Please provide a Bright Data API key")
+            if not url:
+                return ToolResult(content="Please provide a URL to screenshot")
+
+            log_info(f"Taking screenshot of: {url}")
+
+            payload = {
+                "url": url,
+                "zone": self.web_unlocker_zone,
+                "format": "raw",
+                "data_format": "screenshot",
+            }
+
+            response = requests.post(self.endpoint, headers=self.headers, data=json.dumps(payload))
+
+            if response.status_code != 200:
+                raise Exception(f"Error {response.status_code}: {response.text}")
+
+            image_bytes = response.content
+            base64_encoded_image = base64.b64encode(image_bytes).decode("utf-8")
+            log_debug(f"Base64 encoded image: {type(base64_encoded_image)}")
+
+            media_id = str(uuid4())
+
+            # Create Image for the screenshot
+            image_artifact = Image(
+                id=media_id,
+                content=base64_encoded_image.encode("utf-8"),
+                mime_type="image/png",
+                original_prompt=f"Screenshot of {url}",
+            )
+
+            log_debug(f"Screenshot captured and added as artifact with ID: {media_id}")
+            return ToolResult(
+                content=f"Screenshot captured and added as artifact with ID: {media_id}", images=[image_artifact]
+            )
+        except Exception as e:
+            return ToolResult(content=f"Error taking screenshot of {url}: {e}")
+
+    def search_engine(
+        self,
+        query: str,
+        engine: str = "google",
+        num_results: int = 10,
+        language: Optional[str] = None,
+        country_code: Optional[str] = None,
+    ) -> str:
+        """
+        Search using Google, Bing, or Yandex and return results in Markdown.
+
+        Args:
+            query (str): Search query
+            engine (str): Search engine - 'google', 'bing', or 'yandex'
+            num_results (int): Number of results to return
+            language (Optional[str]): Two-letter language code
+            country_code (Optional[str]): Two-letter country code
+
+        Returns:
+            str: Search results as Markdown
+        """
+        try:
+            if not self.api_key:
+                return "Please provide a Bright Data API key"
+            if not query:
+                return "Please provide a query to search for"
+
+            log_info(f"Searching {engine} for: {query}")
+
+            from urllib.parse import quote
+
+            encoded_query = quote(query)
+
+            base_urls = {
+                "google": f"https://www.google.com/search?q={encoded_query}",
+                "bing": f"https://www.bing.com/search?q={encoded_query}",
+                "yandex": f"https://yandex.com/search/?text={encoded_query}",
+            }
+
+            if engine not in base_urls:
+                return f"Unsupported search engine: {engine}. Use 'google', 'bing', or 'yandex'"
+
+            search_url = base_urls[engine]
+
+            if engine == "google":
+                params = []
+                if language:
+                    params.append(f"hl={language}")
+                if country_code:
+                    params.append(f"gl={country_code}")
+                if num_results:
+                    params.append(f"num={num_results}")
+
+                if params:
+                    search_url += "&" + "&".join(params)
+
+            payload = {
+                "url": search_url,
+                "zone": self.serp_zone,
+                "format": "raw",
+                "data_format": "markdown",
+            }
+
+            content = self._make_request(payload)
+            return content
+        except Exception as e:
+            return f"Error searching for query {query}: {e}"
+
+    def web_data_feed(
+        self,
+        source_type: str,
+        url: str,
+        num_of_reviews: Optional[int] = None,
+    ) -> str:
+        """
+        Retrieve structured web data from various sources like LinkedIn, Amazon, Instagram, etc.
+
+        Args:
+            source_type (str): Type of data source (e.g., 'linkedin_person_profile', 'amazon_product')
+            url (str): URL of the web resource to retrieve data from
+            num_of_reviews (Optional[int]): Number of reviews to retrieve
+
+        Returns:
+            str: Structured data from the requested source as JSON
+        """
+        try:
+            if not self.api_key:
+                return "Please provide a Bright Data API key"
+            if not url:
+                return "Please provide a URL to retrieve data from"
+
+            log_info(f"Retrieving {source_type} data from: {url}")
+
+            datasets = {
+                "amazon_product": "gd_l7q7dkf244hwjntr0",
+                "amazon_product_reviews": "gd_le8e811kzy4ggddlq",
+                "amazon_product_search": "gd_lwdb4vjm1ehb499uxs",
+                "walmart_product": "gd_l95fol7l1ru6rlo116",
+                "walmart_seller": "gd_m7ke48w81ocyu4hhz0",
+                "ebay_product": "gd_ltr9mjt81n0zzdk1fb",
+                "homedepot_products": "gd_lmusivh019i7g97q2n",
+                "zara_products": "gd_lct4vafw1tgx27d4o0",
+                "etsy_products": "gd_ltppk0jdv1jqz25mz",
+                "bestbuy_products": "gd_ltre1jqe1jfr7cccf",
+                "linkedin_person_profile": "gd_l1viktl72bvl7bjuj0",
+                "linkedin_company_profile": "gd_l1vikfnt1wgvvqz95w",
+                "linkedin_job_listings": "gd_lpfll7v5hcqtkxl6l",
+                "linkedin_posts": "gd_lyy3tktm25m4avu764",
+                "linkedin_people_search": "gd_m8d03he47z8nwb5xc",
+                "crunchbase_company": "gd_l1vijqt9jfj7olije",
+                "zoominfo_company_profile": "gd_m0ci4a4ivx3j5l6nx",
+                "instagram_profiles": "gd_l1vikfch901nx3by4",
+                "instagram_posts": "gd_lk5ns7kz21pck8jpis",
+                "instagram_reels": "gd_lyclm20il4r5helnj",
+                "instagram_comments": "gd_ltppn085pokosxh13",
+                "facebook_posts": "gd_lyclm1571iy3mv57zw",
+                "facebook_marketplace_listings": "gd_lvt9iwuh6fbcwmx1a",
+                "facebook_company_reviews": "gd_m0dtqpiu1mbcyc2g86",
+                "facebook_events": "gd_m14sd0to1jz48ppm51",
+                "tiktok_profiles": "gd_l1villgoiiidt09ci",
+                "tiktok_posts": "gd_lu702nij2f790tmv9h",
+                "tiktok_shop": "gd_m45m1u911dsa4274pi",
+                "tiktok_comments": "gd_lkf2st302ap89utw5k",
+                "google_maps_reviews": "gd_luzfs1dn2oa0teb81",
+                "google_shopping": "gd_ltppk50q18kdw67omz",
+                "google_play_store": "gd_lsk382l8xei8vzm4u",
+                "apple_app_store": "gd_lsk9ki3u2iishmwrui",
+                "reuter_news": "gd_lyptx9h74wtlvpnfu",
+                "github_repository_file": "gd_lyrexgxc24b3d4imjt",
+                "yahoo_finance_business": "gd_lmrpz3vxmz972ghd7",
+                "x_posts": "gd_lwxkxvnf1cynvib9co",
+                "zillow_properties_listing": "gd_lfqkr8wm13ixtbd8f5",
+                "booking_hotel_listings": "gd_m5mbdl081229ln6t4a",
+                "youtube_profiles": "gd_lk538t2k2p1k3oos71",
+                "youtube_comments": "gd_lk9q0ew71spt1mxywf",
+                "reddit_posts": "gd_lvz8ah06191smkebj4",
+                "youtube_videos": "gd_m5mbdl081229ln6t4a",
+            }
+
+            if source_type not in datasets:
+                valid_sources = ", ".join(datasets.keys())
+                return f"Invalid source_type: {source_type}. Valid options are: {valid_sources}"
+
+            dataset_id = datasets[source_type]
+
+            request_data = {"url": url}
+            if source_type == "facebook_company_reviews" and num_of_reviews is not None:
+                request_data["num_of_reviews"] = str(num_of_reviews)
+
+            trigger_response = requests.post(
+                "https://api.brightdata.com/datasets/v3/trigger",
+                params={"dataset_id": dataset_id, "include_errors": "true"},
+                headers=self.headers,
+                json=[request_data],
+            )
+
+            trigger_data = trigger_response.json()
+            if not trigger_data.get("snapshot_id"):
+                return "No snapshot ID returned from trigger request"
+
+            snapshot_id = trigger_data["snapshot_id"]
+
+            import time
+
+            attempts = 0
+            max_attempts = self.timeout
+
+            while attempts < max_attempts:
+                try:
+                    snapshot_response = requests.get(
+                        f"https://api.brightdata.com/datasets/v3/snapshot/{snapshot_id}",
+                        params={"format": "json"},
+                        headers=self.headers,
+                    )
+
+                    snapshot_data = snapshot_response.json()
+
+                    if isinstance(snapshot_data, dict) and snapshot_data.get("status") == "running":
+                        attempts += 1
+                        time.sleep(1)
+                        continue
+
+                    return json.dumps(snapshot_data)
+
+                except Exception:
+                    attempts += 1
+                    time.sleep(1)
+
+            return f"Timeout after {max_attempts} seconds waiting for {source_type} data"
+
+        except Exception as e:
+            return f"Error retrieving {source_type} data from {url}: {e}"