agno 2.2.13__py3-none-any.whl

agno/tools/sql.py

@@ -0,0 +1,154 @@
+import json
+from typing import Any, Dict, List, Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, logger
+
+try:
+    from sqlalchemy import Engine, create_engine
+    from sqlalchemy.inspection import inspect
+    from sqlalchemy.orm import Session, sessionmaker
+    from sqlalchemy.sql.expression import text
+except ImportError:
+    raise ImportError("`sqlalchemy` not installed")
+
+
+class SQLTools(Toolkit):
+    def __init__(
+        self,
+        db_url: Optional[str] = None,
+        db_engine: Optional[Engine] = None,
+        user: Optional[str] = None,
+        password: Optional[str] = None,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        schema: Optional[str] = None,
+        dialect: Optional[str] = None,
+        tables: Optional[Dict[str, Any]] = None,
+        enable_list_tables: bool = True,
+        enable_describe_table: bool = True,
+        enable_run_sql_query: bool = True,
+        all: bool = False,
+        **kwargs,
+    ):
+        # Get the database engine
+        _engine: Optional[Engine] = db_engine
+        if _engine is None and db_url is not None:
+            _engine = create_engine(db_url)
+        elif user and password and host and port and dialect:
+            if schema is not None:
+                _engine = create_engine(f"{dialect}://{user}:{password}@{host}:{port}/{schema}")
+            else:
+                _engine = create_engine(f"{dialect}://{user}:{password}@{host}:{port}")
+
+        if _engine is None:
+            raise ValueError("Could not build the database connection")
+
+        # Database connection
+        self.db_engine: Engine = _engine
+        self.Session: sessionmaker[Session] = sessionmaker(bind=self.db_engine)
+
+        self.schema = schema
+
+        # Tables this toolkit can access
+        self.tables: Optional[Dict[str, Any]] = tables
+
+        tools: List[Any] = []
+        if enable_list_tables or all:
+            tools.append(self.list_tables)
+        if enable_describe_table or all:
+            tools.append(self.describe_table)
+        if enable_run_sql_query or all:
+            tools.append(self.run_sql_query)
+
+        super().__init__(name="sql_tools", tools=tools, **kwargs)
+
+    def list_tables(self) -> str:
+        """Use this function to get a list of table names in the database.
+
+        Returns:
+            str: list of tables in the database.
+        """
+        if self.tables is not None:
+            return json.dumps(self.tables)
+
+        try:
+            log_debug("listing tables in the database")
+            inspector = inspect(self.db_engine)
+            if self.schema:
+                table_names = inspector.get_table_names(schema=self.schema)
+            else:
+                table_names = inspector.get_table_names()
+            log_debug(f"table_names: {table_names}")
+            return json.dumps(table_names)
+        except Exception as e:
+            logger.error(f"Error getting tables: {e}")
+            return f"Error getting tables: {e}"
+
+    def describe_table(self, table_name: 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:
+            log_debug(f"Describing table: {table_name}")
+            inspector = inspect(self.db_engine)
+            table_schema = inspector.get_columns(table_name, schema=self.schema)
+            return json.dumps(
+                [
+                    {"name": column["name"], "type": str(column["type"]), "nullable": column["nullable"]}
+                    for column in table_schema
+                ]
+            )
+        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, limit: Optional[int] = 10) -> str:
+        """Use this function to run a SQL query and return the result.
+
+        Args:
+            query (str): The query to run.
+            limit (int, optional): The number of rows to return. Defaults to 10. Use `None` to show all results.
+        Returns:
+            str: Result of the 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, limit=limit), 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, limit: Optional[int] = None) -> List[dict]:
+        """Internal function to run a sql query.
+
+        Args:
+            sql (str): The sql query to run.
+            limit (int, optional): The number of rows to return. Defaults to None.
+
+        Returns:
+            List[dict]: The result of the query.
+        """
+        log_debug(f"Running sql |\n{sql}")
+
+        with self.Session() as sess, sess.begin():
+            result = sess.execute(text(sql))
+
+            # Check if the operation has returned rows.
+            try:
+                if limit:
+                    rows = result.fetchmany(limit)
+                else:
+                    rows = result.fetchall()
+                return [row._asdict() for row in rows]
+            except Exception as e:
+                logger.error(f"Error while executing SQL: {e}")
+                return []

agno/tools/streamlit/components.py

@@ -0,0 +1,113 @@
+from os import environ, getenv
+from typing import Optional
+
+try:
+    import streamlit as st
+except ImportError:
+    raise ImportError("`streamlit` library not installed. Please install using `pip install streamlit`")
+
+
+def get_username_sidebar() -> Optional[str]:
+    """Sidebar component to get username"""
+
+    # Get username from user if not in session state
+    if "username" not in st.session_state:
+        username_input_container = st.sidebar.empty()
+        username = username_input_container.text_input(":technologist: Enter username")
+        if username != "":
+            st.session_state["username"] = username
+            username_input_container.empty()
+
+    # Get username from session state
+    username = st.session_state.get("username")  # type: ignore
+    return username
+
+
+def reload_button_sidebar(text: str = "Reload Session", **kwargs) -> None:
+    """Sidebar component to show reload button"""
+
+    if st.sidebar.button(text, **kwargs):
+        st.session_state.clear()
+        st.rerun()
+
+
+def check_password(password_env_var: str = "APP_PASSWORD") -> bool:
+    """Component to check if a password entered by the user is correct.
+    To use this component, set the environment variable `APP_PASSWORD`.
+
+    Args:
+        password_env_var (str, optional): The environment variable to use for the password. Defaults to "APP_PASSWORD".
+
+    Returns:
+        bool: `True` if the user had the correct password.
+    """
+
+    app_password = getenv(password_env_var)
+    if app_password is None:
+        return True
+
+    def check_first_run_password():
+        """Checks whether a password entered on the first run is correct."""
+
+        if "first_run_password" in st.session_state:
+            password_to_check = st.session_state["first_run_password"]
+            if password_to_check == app_password:
+                st.session_state["password_correct"] = True
+                # don't store password
+                del st.session_state["first_run_password"]
+            else:
+                st.session_state["password_correct"] = False
+
+    def check_updated_password():
+        """Checks whether an updated password is correct."""
+
+        if "updated_password" in st.session_state:
+            password_to_check = st.session_state["updated_password"]
+            if password_to_check == app_password:
+                st.session_state["password_correct"] = True
+                # don't store password
+                del st.session_state["updated_password"]
+            else:
+                st.session_state["password_correct"] = False
+
+    # First run, show input for password.
+    if "password_correct" not in st.session_state:
+        st.text_input(
+            "Password",
+            type="password",
+            on_change=check_first_run_password,
+            key="first_run_password",
+        )
+        return False
+    # Password incorrect, show input for updated password + error.
+    elif not st.session_state["password_correct"]:
+        st.text_input(
+            "Password",
+            type="password",
+            on_change=check_updated_password,
+            key="updated_password",
+        )
+        st.error("😕 Password incorrect")
+        return False
+    # Password correct.
+    else:
+        return True
+
+
+def get_openai_key_sidebar() -> Optional[str]:
+    """Sidebar component to get OpenAI API key"""
+
+    # Get OpenAI API key from environment variable
+    openai_key: Optional[str] = getenv("OPENAI_API_KEY")
+    # If not found, get it from user input
+    if openai_key is None or openai_key == "" or openai_key == "sk-***":
+        api_key = st.sidebar.text_input("OpenAI API key", placeholder="sk-***", key="api_key")
+        if api_key != "sk-***" or api_key != "" or api_key is not None:
+            openai_key = api_key
+
+    # Store it in session state and environment variable
+    if openai_key is not None and openai_key != "":
+        st.session_state["OPENAI_API_KEY"] = openai_key
+        environ["OPENAI_API_KEY"] = openai_key
+
+    return openai_key

agno/tools/tavily.py

@@ -0,0 +1,254 @@
+import json
+from os import getenv
+from typing import Any, Dict, List, Literal, Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import logger
+
+try:
+    from tavily import TavilyClient
+except ImportError:
+    raise ImportError("`tavily-python` not installed. Please install using `pip install tavily-python`")
+
+
+class TavilyTools(Toolkit):
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        enable_search: bool = True,
+        enable_search_context: bool = False,
+        enable_extract: bool = False,
+        all: bool = False,
+        max_tokens: int = 6000,
+        include_answer: bool = True,
+        search_depth: Literal["basic", "advanced"] = "advanced",
+        extract_depth: Literal["basic", "advanced"] = "basic",
+        include_images: bool = False,
+        include_favicon: bool = False,
+        extract_timeout: Optional[int] = None,
+        extract_format: Literal["markdown", "text"] = "markdown",
+        format: Literal["json", "markdown"] = "markdown",
+        **kwargs,
+    ):
+        """Initialize TavilyTools with search and extract capabilities.
+
+        Args:
+            api_key: Tavily API key. If not provided, will use TAVILY_API_KEY env var.
+            enable_search: Enable web search functionality. Defaults to True.
+            enable_search_context: Use search context mode instead of regular search. Defaults to False.
+            enable_extract: Enable URL content extraction functionality. Defaults to False.
+            all: Enable all available tools. Defaults to False.
+            max_tokens: Maximum tokens for search results. Defaults to 6000.
+            include_answer: Include AI-generated answer in search results. Defaults to True.
+            search_depth: Search depth level - basic (1 credit) or advanced (2 credits). Defaults to "advanced".
+            extract_depth: Extract depth level - basic (1 credit/5 URLs) or advanced (2 credits/5 URLs). Defaults to "basic".
+            include_images: Include images in extracted content. Defaults to False.
+            include_favicon: Include favicon in extracted content. Defaults to False.
+            extract_timeout: Timeout in seconds for extraction requests. Defaults to None.
+            extract_format: Output format for extracted content - markdown or text. Defaults to "markdown".
+            format: Output format for search results - json or markdown. Defaults to "markdown".
+            **kwargs: Additional arguments passed to Toolkit.
+        """
+        self.api_key = api_key or getenv("TAVILY_API_KEY")
+        if not self.api_key:
+            logger.error("TAVILY_API_KEY not provided")
+
+        self.client: TavilyClient = TavilyClient(api_key=self.api_key)
+        self.search_depth: Literal["basic", "advanced"] = search_depth
+        self.extract_depth: Literal["basic", "advanced"] = extract_depth
+        self.max_tokens: int = max_tokens
+        self.include_answer: bool = include_answer
+        self.include_images: bool = include_images
+        self.include_favicon: bool = include_favicon
+        self.extract_timeout: Optional[int] = extract_timeout
+        self.extract_format: Literal["markdown", "text"] = extract_format
+        self.format: Literal["json", "markdown"] = format
+
+        tools: List[Any] = []
+
+        if enable_search or all:
+            if enable_search_context:
+                tools.append(self.web_search_with_tavily)
+            else:
+                tools.append(self.web_search_using_tavily)
+
+        if enable_extract or all:
+            tools.append(self.extract_url_content)
+
+        super().__init__(name="tavily_tools", tools=tools, **kwargs)
+
+    def web_search_using_tavily(self, query: str, max_results: int = 5) -> str:
+        """Use this function to search the web for a given query.
+        This function uses the Tavily API to provide realtime online information about the query.
+
+        Args:
+            query (str): Query to search for.
+            max_results (int): Maximum number of results to return. Defaults to 5.
+
+        Returns:
+            str: JSON string of results related to the query.
+        """
+
+        response = self.client.search(
+            query=query, search_depth=self.search_depth, include_answer=self.include_answer, max_results=max_results
+        )
+
+        clean_response: Dict[str, Any] = {"query": query}
+        if "answer" in response:
+            clean_response["answer"] = response["answer"]
+
+        clean_results = []
+        current_token_count = len(json.dumps(clean_response))
+        for result in response.get("results", []):
+            _result = {
+                "title": result["title"],
+                "url": result["url"],
+                "content": result["content"],
+                "score": result["score"],
+            }
+            current_token_count += len(json.dumps(_result))
+            if current_token_count > self.max_tokens:
+                break
+            clean_results.append(_result)
+        clean_response["results"] = clean_results
+
+        if self.format == "json":
+            return json.dumps(clean_response) if clean_response else "No results found."
+        elif self.format == "markdown":
+            _markdown = ""
+            _markdown += f"# {query}\n\n"
+            if "answer" in clean_response:
+                _markdown += "### Summary\n"
+                _markdown += f"{clean_response.get('answer')}\n\n"
+            for result in clean_response["results"]:
+                _markdown += f"### [{result['title']}]({result['url']})\n"
+                _markdown += f"{result['content']}\n\n"
+            return _markdown
+
+    def web_search_with_tavily(self, query: str) -> str:
+        """Use this function to search the web for a given query.
+        This function uses the Tavily API to provide realtime online information about the query.
+
+        Args:
+            query (str): Query to search for.
+
+        Returns:
+            str: JSON string of results related to the query.
+        """
+
+        return self.client.get_search_context(
+            query=query, search_depth=self.search_depth, max_tokens=self.max_tokens, include_answer=self.include_answer
+        )
+
+    def extract_url_content(self, urls: str) -> str:
+        """Extract content from one or more URLs using Tavily's Extract API.
+        This function retrieves the main content from web pages in markdown or text format.
+
+        Args:
+            urls (str): Single URL or multiple comma-separated URLs to extract content from.
+                       Example: "https://example.com" or "https://example.com,https://another.com"
+
+        Returns:
+            str: Extracted content in the specified format (markdown or text).
+                 For multiple URLs, returns combined content with URL headers.
+                 Failed extractions are noted in the output.
+        """
+        # Parse URLs - handle both single and comma-separated multiple URLs
+        url_list = [url.strip() for url in urls.split(",") if url.strip()]
+
+        if not url_list:
+            return "Error: No valid URLs provided."
+
+        try:
+            # Prepare extract parameters
+            extract_params: Dict[str, Any] = {
+                "urls": url_list,
+                "depth": self.extract_depth,
+            }
+
+            # Add optional parameters if specified
+            if self.include_images:
+                extract_params["include_images"] = True
+            if self.include_favicon:
+                extract_params["include_favicon"] = True
+            if self.extract_timeout is not None:
+                extract_params["timeout"] = self.extract_timeout
+
+            # Call Tavily Extract API
+            response = self.client.extract(**extract_params)
+
+            # Process response based on format preference
+            if not response or "results" not in response:
+                return "Error: No content could be extracted from the provided URL(s)."
+
+            results = response.get("results", [])
+            if not results:
+                return "Error: No content could be extracted from the provided URL(s)."
+
+            # Format output
+            if self.extract_format == "markdown":
+                return self._format_extract_markdown(results)
+            elif self.extract_format == "text":
+                return self._format_extract_text(results)
+            else:
+                # Fallback to JSON if format is unrecognized
+                return json.dumps(results, indent=2)
+
+        except Exception as e:
+            logger.error(f"Error extracting content from URLs: {e}")
+            return f"Error extracting content: {str(e)}"
+
+    def _format_extract_markdown(self, results: List[Dict[str, Any]]) -> str:
+        """Format extraction results as markdown.
+
+        Args:
+            results: List of extraction result dictionaries from Tavily API.
+
+        Returns:
+            str: Formatted markdown content.
+        """
+        output = []
+
+        for result in results:
+            url = result.get("url", "Unknown URL")
+            raw_content = result.get("raw_content", "")
+            failed_reason = result.get("failed_reason")
+
+            if failed_reason:
+                output.append(f"## {url}\n\n **Extraction Failed**: {failed_reason}\n\n")
+            elif raw_content:
+                output.append(f"## {url}\n\n{raw_content}\n\n")
+            else:
+                output.append(f"## {url}\n\n*No content available*\n\n")
+
+        return "".join(output) if output else "No content extracted."
+
+    def _format_extract_text(self, results: List[Dict[str, Any]]) -> str:
+        """Format extraction results as plain text.
+
+        Args:
+            results: List of extraction result dictionaries from Tavily API.
+
+        Returns:
+            str: Formatted plain text content.
+        """
+        output = []
+
+        for result in results:
+            url = result.get("url", "Unknown URL")
+            raw_content = result.get("raw_content", "")
+            failed_reason = result.get("failed_reason")
+
+            output.append(f"URL: {url}")
+            output.append("-" * 80)
+
+            if failed_reason:
+                output.append(f"EXTRACTION FAILED: {failed_reason}")
+            elif raw_content:
+                output.append(raw_content)
+            else:
+                output.append("No content available")
+
+            output.append("\n")
+
+        return "\n".join(output) if output else "No content extracted."

agno/tools/telegram.py

@@ -0,0 +1,48 @@
+from os import getenv
+from typing import Any, List, Optional, Union
+
+import httpx
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, logger
+
+
+class TelegramTools(Toolkit):
+    base_url = "https://api.telegram.org"
+
+    def __init__(
+        self,
+        chat_id: Union[str, int],
+        token: Optional[str] = None,
+        enable_send_message: bool = True,
+        all: bool = False,
+        **kwargs,
+    ):
+        self.token = token or getenv("TELEGRAM_TOKEN")
+        if not self.token:
+            logger.error("TELEGRAM_TOKEN not set. Please set the TELEGRAM_TOKEN environment variable.")
+
+        self.chat_id = chat_id
+
+        tools: List[Any] = []
+        if all or enable_send_message:
+            tools.append(self.send_message)
+
+        super().__init__(name="telegram", tools=tools, **kwargs)
+
+    def _call_post_method(self, method, *args, **kwargs):
+        return httpx.post(f"{self.base_url}/bot{self.token}/{method}", *args, **kwargs)
+
+    def send_message(self, message: str) -> str:
+        """This function sends a message to the chat ID.
+
+        :param message: The message to send.
+        :return: The response from the API.
+        """
+        log_debug(f"Sending telegram message: {message}")
+        response = self._call_post_method("sendMessage", json={"chat_id": self.chat_id, "text": message})
+        try:
+            response.raise_for_status()
+            return response.text
+        except httpx.HTTPStatusError as e:
+            return f"An error occurred: {e}"