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

agno/tools/notion.py

@@ -0,0 +1,204 @@
+import json
+import os
+from typing import Any, Dict, List, Optional, cast
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, logger
+
+try:
+    from notion_client import Client
+except ImportError:
+    raise ImportError("`notion-client` not installed. Please install using `pip install notion-client`")
+
+
+class NotionTools(Toolkit):
+    """
+    Notion toolkit for creating and managing Notion pages.
+
+    Args:
+        api_key (Optional[str]): Notion API key (integration token). If not provided, uses NOTION_API_KEY env var.
+        database_id (Optional[str]): The ID of the database to work with. If not provided, uses NOTION_DATABASE_ID env var.
+        enable_create_page (bool): Enable creating pages. Default is True.
+        enable_update_page (bool): Enable updating pages. Default is True.
+        enable_search_pages (bool): Enable searching pages. Default is True.
+        all (bool): Enable all tools. Overrides individual flags when True. Default is False.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        database_id: Optional[str] = None,
+        enable_create_page: bool = True,
+        enable_update_page: bool = True,
+        enable_search_pages: bool = True,
+        all: bool = False,
+        **kwargs,
+    ):
+        self.api_key = api_key or os.getenv("NOTION_API_KEY")
+        self.database_id = database_id or os.getenv("NOTION_DATABASE_ID")
+
+        if not self.api_key:
+            raise ValueError(
+                "Notion API key is required. Either pass api_key parameter or set NOTION_API_KEY environment variable."
+            )
+        if not self.database_id:
+            raise ValueError(
+                "Notion database ID is required. Either pass database_id parameter or set NOTION_DATABASE_ID environment variable."
+            )
+
+        self.client = Client(auth=self.api_key)
+
+        tools: List[Any] = []
+        if all or enable_create_page:
+            tools.append(self.create_page)
+        if all or enable_update_page:
+            tools.append(self.update_page)
+        if all or enable_search_pages:
+            tools.append(self.search_pages)
+
+        super().__init__(name="notion_tools", tools=tools, **kwargs)
+
+    def create_page(self, title: str, tag: str, content: str) -> str:
+        """Create a new page in the Notion database with a title, tag, and content.
+
+        Args:
+            title (str): The title of the page
+            tag (str): The tag/category for the page (e.g., travel, tech, general-blogs, fashion, documents)
+            content (str): The content to add to the page
+
+        Returns:
+            str: JSON string with page creation details
+        """
+        try:
+            log_debug(f"Creating Notion page with title: {title}, tag: {tag}")
+
+            # Create the page in the database
+            new_page = cast(
+                Dict[str, Any],
+                self.client.pages.create(
+                    parent={"database_id": self.database_id},
+                    properties={"Name": {"title": [{"text": {"content": title}}]}, "Tag": {"select": {"name": tag}}},
+                    children=[
+                        {
+                            "object": "block",
+                            "type": "paragraph",
+                            "paragraph": {"rich_text": [{"type": "text", "text": {"content": content}}]},
+                        }
+                    ],
+                ),
+            )
+
+            result = {"success": True, "page_id": new_page["id"], "url": new_page["url"], "title": title, "tag": tag}
+            return json.dumps(result, indent=2)
+
+        except Exception as e:
+            logger.exception(e)
+            return json.dumps({"success": False, "error": str(e)})
+
+    def update_page(self, page_id: str, content: str) -> str:
+        """Add content to an existing Notion page.
+
+        Args:
+            page_id (str): The ID of the page to update
+            content (str): The content to append to the page
+
+        Returns:
+            str: JSON string with update status
+        """
+        try:
+            log_debug(f"Updating Notion page: {page_id}")
+
+            # Append content to the page
+            self.client.blocks.children.append(
+                block_id=page_id,
+                children=[
+                    {
+                        "object": "block",
+                        "type": "paragraph",
+                        "paragraph": {"rich_text": [{"type": "text", "text": {"content": content}}]},
+                    }
+                ],
+            )
+
+            result = {"success": True, "page_id": page_id, "message": "Content added successfully"}
+            return json.dumps(result, indent=2)
+
+        except Exception as e:
+            logger.exception(e)
+            return json.dumps({"success": False, "error": str(e)})
+
+    def search_pages(self, tag: str) -> str:
+        """Search for pages in the database by tag.
+
+        Args:
+            tag (str): The tag to search for
+
+        Returns:
+            str: JSON string with list of matching pages
+        """
+        try:
+            log_debug(f"Searching for pages with tag: {tag}")
+
+            import httpx
+
+            headers = {
+                "Authorization": f"Bearer {self.api_key}",
+                "Notion-Version": "2022-06-28",
+                "Content-Type": "application/json",
+            }
+
+            payload = {"filter": {"property": "Tag", "select": {"equals": tag}}}
+
+            # The SDK client does not support the query method
+            response = httpx.post(
+                f"https://api.notion.com/v1/databases/{self.database_id}/query",
+                headers=headers,
+                json=payload,
+                timeout=30.0,
+            )
+
+            if response.status_code != 200:
+                return json.dumps(
+                    {
+                        "success": False,
+                        "error": f"API request failed with status {response.status_code}",
+                        "message": response.text,
+                    }
+                )
+
+            data = response.json()
+            pages = []
+
+            for page in data.get("results", []):
+                try:
+                    page_title = "Untitled"
+                    if page.get("properties", {}).get("Name", {}).get("title"):
+                        page_title = page["properties"]["Name"]["title"][0]["text"]["content"]
+
+                    page_tag = None
+                    if page.get("properties", {}).get("Tag", {}).get("select"):
+                        page_tag = page["properties"]["Tag"]["select"]["name"]
+
+                    page_info = {
+                        "page_id": page["id"],
+                        "title": page_title,
+                        "tag": page_tag,
+                        "url": page.get("url", ""),
+                    }
+                    pages.append(page_info)
+                except Exception as page_error:
+                    log_debug(f"Error parsing page: {page_error}")
+                    continue
+
+            result = {"success": True, "count": len(pages), "pages": pages}
+            return json.dumps(result, indent=2)
+
+        except Exception as e:
+            logger.exception(e)
+            return json.dumps(
+                {
+                    "success": False,
+                    "error": str(e),
+                    "message": "Failed to search pages. Make sure the database is shared with the integration and has a 'Tag' property.",
+                }
+            )

agno/tools/parallel.py

@@ -0,0 +1,314 @@
+import json
+from os import getenv
+from typing import Any, Dict, List, Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import log_error
+
+try:
+    from parallel import Parallel as ParallelClient
+except ImportError:
+    raise ImportError("`parallel-web` not installed. Please install using `pip install parallel-web`")
+
+
+class CustomJSONEncoder(json.JSONEncoder):
+    """Custom JSON encoder that handles non-serializable types by converting them to strings."""
+
+    def default(self, obj):
+        try:
+            return super().default(obj)
+        except TypeError:
+            return str(obj)
+
+
+class ParallelTools(Toolkit):
+    """
+    ParallelTools provides access to Parallel's web search and extraction APIs.
+
+    Parallel offers powerful APIs optimized for AI agents:
+    - Search API: AI-optimized web search that returns relevant excerpts tailored for LLMs
+    - Extract API: Extract content from specific URLs in clean markdown format, handling JavaScript-heavy pages and PDFs
+
+    Args:
+        api_key (Optional[str]): Parallel API key. If not provided, will use PARALLEL_API_KEY environment variable.
+        enable_search (bool): Enable Search API functionality. Default is True.
+        enable_extract (bool): Enable Extract API functionality. Default is True.
+        all (bool): Enable all tools. Overrides individual flags when True. Default is False.
+        max_results (int): Default maximum number of results for search operations. Default is 10.
+        max_chars_per_result (int): Default maximum characters per result for search operations. Default is 10000.
+        beta_version (str): Beta API version header. Default is "search-extract-2025-10-10".
+        mode (Optional[str]): Default search mode. Options: "one-shot" or "agentic". Default is None.
+        include_domains (Optional[List[str]]): Default domains to restrict results to. Default is None.
+        exclude_domains (Optional[List[str]]): Default domains to exclude from results. Default is None.
+        max_age_seconds (Optional[int]): Default cache age threshold (minimum 600). Default is None.
+        timeout_seconds (Optional[float]): Default timeout for content retrieval. Default is None.
+        disable_cache_fallback (Optional[bool]): Default cache fallback behavior. Default is None.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        enable_search: bool = True,
+        enable_extract: bool = True,
+        all: bool = False,
+        max_results: int = 10,
+        max_chars_per_result: int = 10000,
+        beta_version: str = "search-extract-2025-10-10",
+        mode: Optional[str] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        max_age_seconds: Optional[int] = None,
+        timeout_seconds: Optional[float] = None,
+        disable_cache_fallback: Optional[bool] = None,
+        **kwargs,
+    ):
+        self.api_key: Optional[str] = api_key or getenv("PARALLEL_API_KEY")
+        if not self.api_key:
+            log_error("PARALLEL_API_KEY not set. Please set the PARALLEL_API_KEY environment variable.")
+
+        self.max_results = max_results
+        self.max_chars_per_result = max_chars_per_result
+        self.beta_version = beta_version
+        self.mode = mode
+        self.include_domains = include_domains
+        self.exclude_domains = exclude_domains
+        self.max_age_seconds = max_age_seconds
+        self.timeout_seconds = timeout_seconds
+        self.disable_cache_fallback = disable_cache_fallback
+
+        self.parallel_client = ParallelClient(
+            api_key=self.api_key, default_headers={"parallel-beta": self.beta_version}
+        )
+
+        tools: List[Any] = []
+        if all or enable_search:
+            tools.append(self.parallel_search)
+        if all or enable_extract:
+            tools.append(self.parallel_extract)
+
+        super().__init__(name="parallel_tools", tools=tools, **kwargs)
+
+    def parallel_search(
+        self,
+        objective: Optional[str] = None,
+        search_queries: Optional[List[str]] = None,
+        max_results: Optional[int] = None,
+        max_chars_per_result: Optional[int] = None,
+    ) -> str:
+        """Use this function to search the web using Parallel's Search API with a natural language objective.
+        You must provide at least one of objective or search_queries.
+
+        Args:
+            objective (Optional[str]): Natural-language description of what the web search is trying to find.
+            search_queries (Optional[List[str]]): Traditional keyword queries with optional search operators.
+            max_results (Optional[int]): Upper bound on results returned. Overrides constructor default.
+            max_chars_per_result (Optional[int]): Upper bound on total characters per url for excerpts.
+
+        Returns:
+            str: A JSON formatted string containing the search results with URLs, titles, publish dates, and relevant excerpts.
+        """
+        try:
+            if not objective and not search_queries:
+                return json.dumps({"error": "Please provide at least one of: objective or search_queries"}, indent=2)
+
+            # Use instance defaults if not provided
+            final_max_results = max_results if max_results is not None else self.max_results
+
+            search_params: Dict[str, Any] = {
+                "max_results": final_max_results,
+            }
+
+            # Add objective if provided
+            if objective:
+                search_params["objective"] = objective
+
+            # Add search_queries if provided
+            if search_queries:
+                search_params["search_queries"] = search_queries
+
+            # Add mode from constructor default
+            if self.mode:
+                search_params["mode"] = self.mode
+
+            # Add excerpts configuration
+            excerpts_config: Dict[str, Any] = {}
+            final_max_chars = max_chars_per_result if max_chars_per_result is not None else self.max_chars_per_result
+            if final_max_chars is not None:
+                excerpts_config["max_chars_per_result"] = final_max_chars
+
+            if excerpts_config:
+                search_params["excerpts"] = excerpts_config
+
+            # Add source_policy from constructor defaults
+            source_policy: Dict[str, Any] = {}
+            if self.include_domains:
+                source_policy["include_domains"] = self.include_domains
+            if self.exclude_domains:
+                source_policy["exclude_domains"] = self.exclude_domains
+
+            if source_policy:
+                search_params["source_policy"] = source_policy
+
+            # Add fetch_policy from constructor defaults
+            fetch_policy: Dict[str, Any] = {}
+            if self.max_age_seconds is not None:
+                fetch_policy["max_age_seconds"] = self.max_age_seconds
+            if self.timeout_seconds is not None:
+                fetch_policy["timeout_seconds"] = self.timeout_seconds
+            if self.disable_cache_fallback is not None:
+                fetch_policy["disable_cache_fallback"] = self.disable_cache_fallback
+
+            if fetch_policy:
+                search_params["fetch_policy"] = fetch_policy
+
+            search_result = self.parallel_client.beta.search(**search_params)
+
+            # Use model_dump() if available, otherwise convert to dict
+            try:
+                if hasattr(search_result, "model_dump"):
+                    return json.dumps(search_result.model_dump(), cls=CustomJSONEncoder)
+            except Exception:
+                pass
+
+            # Manually format the results
+            formatted_results: Dict[str, Any] = {
+                "search_id": getattr(search_result, "search_id", ""),
+                "results": [],
+            }
+
+            if hasattr(search_result, "results") and search_result.results:
+                results_list: List[Dict[str, Any]] = []
+                for result in search_result.results:
+                    formatted_result: Dict[str, Any] = {
+                        "title": getattr(result, "title", ""),
+                        "url": getattr(result, "url", ""),
+                        "publish_date": getattr(result, "publish_date", ""),
+                        "excerpt": getattr(result, "excerpt", ""),
+                    }
+                    results_list.append(formatted_result)
+                formatted_results["results"] = results_list
+
+            if hasattr(search_result, "warnings"):
+                formatted_results["warnings"] = search_result.warnings
+
+            if hasattr(search_result, "usage"):
+                formatted_results["usage"] = search_result.usage
+
+            return json.dumps(formatted_results, cls=CustomJSONEncoder, indent=2)
+
+        except Exception as e:
+            log_error(f"Error searching Parallel for objective '{objective}': {e}")
+            return json.dumps({"error": f"Search failed: {str(e)}"}, indent=2)
+
+    def parallel_extract(
+        self,
+        urls: List[str],
+        objective: Optional[str] = None,
+        search_queries: Optional[List[str]] = None,
+        excerpts: bool = True,
+        max_chars_per_excerpt: Optional[int] = None,
+        full_content: bool = False,
+        max_chars_for_full_content: Optional[int] = None,
+    ) -> str:
+        """Use this function to extract content from specific URLs using Parallel's Extract API.
+
+        Args:
+            urls (List[str]): List of public URLs to extract content from.
+            objective (Optional[str]): Search focus to guide content extraction.
+            search_queries (Optional[List[str]]): Keywords for targeting relevant content.
+            excerpts (bool): Include relevant text snippets.
+            max_chars_per_excerpt (Optional[int]): Upper bound on total characters per url. Only used when excerpts is True.
+            full_content (bool): Include complete page text.
+            max_chars_for_full_content (Optional[int]): Limit on characters per url. Only used when full_content is True.
+
+        Returns:
+            str: A JSON formatted string containing extracted content with titles, publish dates, excerpts and/or full content.
+        """
+        try:
+            if not urls:
+                return json.dumps({"error": "Please provide at least one URL to extract"}, indent=2)
+
+            extract_params: Dict[str, Any] = {
+                "urls": urls,
+            }
+
+            # Add objective if provided
+            if objective:
+                extract_params["objective"] = objective
+
+            # Add search_queries if provided
+            if search_queries:
+                extract_params["search_queries"] = search_queries
+
+            # Add excerpts configuration
+            if excerpts and max_chars_per_excerpt is not None:
+                extract_params["excerpts"] = {"max_chars_per_result": max_chars_per_excerpt}
+            else:
+                extract_params["excerpts"] = excerpts
+
+            # Add full_content configuration
+            if full_content and max_chars_for_full_content is not None:
+                extract_params["full_content"] = {"max_chars_per_result": max_chars_for_full_content}
+            else:
+                extract_params["full_content"] = full_content
+
+            # Add fetch_policy from constructor defaults
+            fetch_policy: Dict[str, Any] = {}
+            if self.max_age_seconds is not None:
+                fetch_policy["max_age_seconds"] = self.max_age_seconds
+            if self.timeout_seconds is not None:
+                fetch_policy["timeout_seconds"] = self.timeout_seconds
+            if self.disable_cache_fallback is not None:
+                fetch_policy["disable_cache_fallback"] = self.disable_cache_fallback
+
+            if fetch_policy:
+                extract_params["fetch_policy"] = fetch_policy
+
+            extract_result = self.parallel_client.beta.extract(**extract_params)
+
+            # Use model_dump() if available, otherwise convert to dict
+            try:
+                if hasattr(extract_result, "model_dump"):
+                    return json.dumps(extract_result.model_dump(), cls=CustomJSONEncoder)
+            except Exception:
+                pass
+
+            # Manually format the results
+            formatted_results: Dict[str, Any] = {
+                "extract_id": getattr(extract_result, "extract_id", ""),
+                "results": [],
+                "errors": [],
+            }
+
+            if hasattr(extract_result, "results") and extract_result.results:
+                results_list: List[Dict[str, Any]] = []
+                for result in extract_result.results:
+                    formatted_result: Dict[str, Any] = {
+                        "url": getattr(result, "url", ""),
+                        "title": getattr(result, "title", ""),
+                        "publish_date": getattr(result, "publish_date", ""),
+                    }
+
+                    if excerpts and hasattr(result, "excerpts"):
+                        formatted_result["excerpts"] = result.excerpts
+
+                    if full_content and hasattr(result, "full_content"):
+                        formatted_result["full_content"] = result.full_content
+
+                    results_list.append(formatted_result)
+                formatted_results["results"] = results_list
+
+            if hasattr(extract_result, "errors") and extract_result.errors:
+                formatted_results["errors"] = extract_result.errors
+
+            if hasattr(extract_result, "warnings"):
+                formatted_results["warnings"] = extract_result.warnings
+
+            if hasattr(extract_result, "usage"):
+                formatted_results["usage"] = extract_result.usage
+
+            return json.dumps(formatted_results, cls=CustomJSONEncoder, indent=2)
+
+        except Exception as e:
+            log_error(f"Error extracting from Parallel: {e}")
+            return json.dumps({"error": f"Extract failed: {str(e)}"}, indent=2)

agno/tools/postgres.py

@@ -14,6 +14,21 @@ from agno.utils.log import log_debug, log_error
 
 
 class PostgresTools(Toolkit):
+    """
+    A toolkit for interacting with PostgreSQL databases.
+
+    Args:
+        connection (Optional[PgConnection[DictRow]]): Existing database connection to reuse.
+        db_name (Optional[str]): Database name to connect to.
+        user (Optional[str]): Username for authentication.
+        password (Optional[str]): Password for authentication.
+        host (Optional[str]): PostgreSQL server hostname.
+        port (Optional[int]): PostgreSQL server port number.
+        table_schema (str): Default schema for table operations. Default is "public".
+    """
+
+    _requires_connect: bool = True
+
     def __init__(
         self,
         connection: Optional[PgConnection[DictRow]] = None,
@@ -44,50 +59,71 @@ class PostgresTools(Toolkit):
 
         super().__init__(name="postgres_tools", tools=tools, **kwargs)
 
-    @property
-    def connection(self) -> PgConnection[DictRow]:
-        """
-        Returns the Postgres psycopg connection.
-        :return psycopg.connection.Connection: psycopg connection
+    def connect(self) -> PgConnection[DictRow]:
         """
-        if self._connection is None or self._connection.closed:
-            log_debug("Establishing new PostgreSQL connection.")
-            connection_kwargs: Dict[str, Any] = {"row_factory": dict_row}
-            if self.db_name:
-                connection_kwargs["dbname"] = self.db_name
-            if self.user:
-                connection_kwargs["user"] = self.user
-            if self.password:
-                connection_kwargs["password"] = self.password
-            if self.host:
-                connection_kwargs["host"] = self.host
-            if self.port:
-                connection_kwargs["port"] = self.port
-
-            connection_kwargs["options"] = f"-c search_path={self.table_schema}"
-
-            self._connection = psycopg.connect(**connection_kwargs)
-            self._connection.read_only = True
+        Establish a connection to the PostgreSQL database.
 
+        Returns:
+            The database connection object.
+        """
+        if self._connection is not None and not self._connection.closed:
+            log_debug("Connection already established, reusing existing connection")
+            return self._connection
+
+        log_debug("Establishing new PostgreSQL connection.")
+        connection_kwargs: Dict[str, Any] = {"row_factory": dict_row}
+        if self.db_name:
+            connection_kwargs["dbname"] = self.db_name
+        if self.user:
+            connection_kwargs["user"] = self.user
+        if self.password:
+            connection_kwargs["password"] = self.password
+        if self.host:
+            connection_kwargs["host"] = self.host
+        if self.port:
+            connection_kwargs["port"] = self.port
+
+        connection_kwargs["options"] = f"-c search_path={self.table_schema}"
+
+        self._connection = psycopg.connect(**connection_kwargs)
+        self._connection.read_only = True
         return self._connection
 
-    def __enter__(self):
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        self.close()
-
-    def close(self):
+    def close(self) -> None:
         """Closes the database connection if it's open."""
         if self._connection and not self._connection.closed:
             log_debug("Closing PostgreSQL connection.")
             self._connection.close()
             self._connection = None
 
+    @property
+    def is_connected(self) -> bool:
+        """Check if a connection is currently established."""
+        return self._connection is not None and not self._connection.closed
+
+    def _ensure_connection(self) -> PgConnection[DictRow]:
+        """
+        Ensure a connection exists, creating one if necessary.
+
+        Returns:
+            The database connection object.
+        """
+        if not self.is_connected:
+            return self.connect()
+        return self._connection  # type: ignore
+
+    def __enter__(self):
+        return self.connect()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.is_connected:
+            self.close()
+
     def _execute_query(self, query: str, params: Optional[tuple] = None) -> str:
         try:
-            with self.connection.cursor() as cursor:
-                log_debug(f"Running PostgreSQL Query: {query} with Params: {params}")
+            connection = self._ensure_connection()
+            with connection.cursor() as cursor:
+                log_debug("Running PostgreSQL query")
                 cursor.execute(query, params)
 
                 if cursor.description is None:
@@ -105,8 +141,8 @@ class PostgresTools(Toolkit):
 
         except psycopg.Error as e:
             log_error(f"Database error: {e}")
-            if self.connection and not self.connection.closed:
-                self.connection.rollback()
+            if self._connection and not self._connection.closed:
+                self._connection.rollback()
             return f"Error executing query: {e}"
         except Exception as e:
             log_error(f"An unexpected error occurred: {e}")
@@ -146,7 +182,8 @@ class PostgresTools(Toolkit):
             A string containing a summary of the table.
         """
         try:
-            with self.connection.cursor() as cursor:
+            connection = self._ensure_connection()
+            with connection.cursor() as cursor:
                 # First, get column information using a parameterized query
                 schema_query = """
                     SELECT column_name, data_type
@@ -230,7 +267,8 @@ class PostgresTools(Toolkit):
         stmt = sql.SQL("SELECT * FROM {tbl};").format(tbl=table_identifier)
 
         try:
-            with self.connection.cursor() as cursor:
+            connection = self._ensure_connection()
+            with connection.cursor() as cursor:
                 cursor.execute(stmt)
 
                 if cursor.description is None:
@@ -245,6 +283,8 @@ class PostgresTools(Toolkit):
 
             return f"Successfully exported table '{table}' to '{path}'."
         except (psycopg.Error, IOError) as e:
+            if self._connection and not self._connection.closed:
+                self._connection.rollback()
             return f"Error exporting table: {e}"
 
     def run_query(self, query: str) -> str: