agno 2.2.13__py3-none-any.whl

agno/tools/linear.py

@@ -0,0 +1,426 @@
+from os import getenv
+from typing import Any, List, Optional
+
+import requests
+
+from agno.tools import Toolkit
+from agno.utils.log import log_info, logger
+
+
+class LinearTools(Toolkit):
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        **kwargs,
+    ):
+        self.api_key = api_key or getenv("LINEAR_API_KEY")
+
+        if not self.api_key:
+            raise ValueError("Linear API key is required")
+
+        self.endpoint = "https://api.linear.app/graphql"
+        self.headers = {"Authorization": f"{self.api_key}"}
+
+        tools: List[Any] = [
+            self.get_user_details,
+            self.get_teams_details,
+            self.get_issue_details,
+            self.create_issue,
+            self.update_issue,
+            self.get_user_assigned_issues,
+            self.get_workflow_issues,
+            self.get_high_priority_issues,
+        ]
+
+        super().__init__(name="linear_tools", tools=tools, **kwargs)
+
+    def _execute_query(self, query, variables=None):
+        """Helper method to execute GraphQL queries with optional variables."""
+
+        try:
+            response = requests.post(self.endpoint, json={"query": query, "variables": variables}, headers=self.headers)
+            response.raise_for_status()
+
+            data = response.json()
+
+            if "errors" in data:
+                logger.error(f"GraphQL Error: {data['errors']}")
+                raise Exception(f"GraphQL Error: {data['errors']}")
+
+            log_info("GraphQL query executed successfully.")
+            return data.get("data")
+
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request error: {e}")
+            raise
+
+        except Exception as e:
+            logger.error(f"Unexpected error: {e}")
+            raise
+
+    def get_user_details(self) -> Optional[str]:
+        """
+        Fetch authenticated user details.
+        It will return the user's unique ID, name, and email address from the viewer object in the GraphQL response.
+
+        Returns:
+            str or None: A string containing user details like user id, name, and email.
+
+        Raises:
+            Exception: If an error occurs during the query execution or data retrieval.
+        """
+
+        query = """
+        query Me {
+          viewer {
+            id
+            name
+            email
+          }
+        }
+        """
+
+        try:
+            response = self._execute_query(query)
+
+            if response.get("viewer"):
+                user = response["viewer"]
+                log_info(
+                    f"Retrieved authenticated user details with name: {user['name']}, ID: {user['id']}, Email: {user['email']}"
+                )
+                return str(user)
+            else:
+                logger.error("Failed to retrieve the current user details")
+                return None
+
+        except Exception as e:
+            logger.error(f"Error fetching authenticated user details: {e}")
+            raise
+
+    def get_teams_details(self) -> Optional[str]:
+        """
+        Fetch the list of authenticated teams.
+        It will return the unique ID and team name for each team, from the viewer object in the GraphQL response.
+
+        Returns:
+            str or None: A dictionary containing team details like team name, id.
+
+        Raises:
+            Exception: If an error occurs during the query execution or data retrieval.
+        """
+
+        query = """
+        query Teams {
+          teams {
+            nodes {
+              id
+              name
+            }
+          }
+        }
+        """
+
+        try:
+            response = self._execute_query(query)
+
+            if response.get("teams"):
+                teams = response["teams"]["nodes"]
+                log_info(f"Retrieved authenticated team details: {teams}")
+                return str(teams)
+            else:
+                logger.error("Failed to retrieve the current user details")
+                return None
+
+        except Exception as e:
+            logger.error(f"Error fetching authenticated user details: {e}")
+            raise
+
+    def get_issue_details(self, issue_id: str) -> Optional[str]:
+        """
+        Retrieve details of a specific issue by issue ID.
+
+        Args:
+            issue_id (str): The unique identifier of the issue to retrieve.
+
+        Returns:
+            str or None: A string containing issue details like issue id, issue title, and issue description.
+                  Returns `None` if the issue is not found.
+
+        Raises:
+            Exception: If an error occurs during the query execution or data retrieval.
+        """
+
+        query = """
+        query IssueDetails ($issueId: String!){
+        issue(id: $issueId) {
+          id
+          title
+          description
+          }
+        }
+        """
+        variables = {"issueId": issue_id}
+        try:
+            response = self._execute_query(query, variables)
+
+            if response.get("issue"):
+                issue = response["issue"]
+                log_info(f"Issue '{issue['title']}' retrieved successfully with ID {issue['id']}.")
+                return str(issue)
+            else:
+                logger.error(f"Failed to retrieve issue with ID {issue_id}.")
+                return None
+
+        except Exception as e:
+            logger.error(f"Error retrieving issue with ID {issue_id}: {e}")
+            raise
+
+    def create_issue(
+        self,
+        title: str,
+        description: str,
+        team_id: str,
+        project_id: Optional[str] = None,
+        assignee_id: Optional[str] = None,
+    ) -> Optional[str]:
+        """
+        Create a new issue within a specific project and team.
+
+        Args:
+            title (str): The title of the new issue.
+            description (str): The description of the new issue.
+            team_id (str): The unique identifier of the team in which to create the issue.
+            project_id (Optional[str]): The ID of the project (optional).
+            assignee_id (Optional[str]): The ID of the assignee (optional).
+
+        Returns:
+            str or None: A string containing the created issue's details like issue id and issue title.
+                  Returns `None` if the issue creation fails.
+
+        Raises:
+            Exception: If an error occurs during the mutation execution or data retrieval.
+        """
+
+        query = """
+        mutation IssueCreate ($title: String!, $description: String!, $teamId: String!, $projectId: String, $assigneeId: String){
+          issueCreate(
+            input: { title: $title, description: $description, teamId: $teamId, projectId: $projectId, assigneeId: $assigneeId}
+          ) {
+            success
+            issue {
+              id
+              title
+              url
+            }
+          }
+        }
+        """
+
+        variables = {
+            "title": title,
+            "description": description,
+            "teamId": team_id,
+        }
+        if project_id is not None:
+            variables["projectId"] = project_id
+        if assignee_id is not None:
+            variables["assigneeId"] = assignee_id
+
+        try:
+            response = self._execute_query(query, variables)
+            log_info(f"Response: {response}")
+
+            if response["issueCreate"]["success"]:
+                issue = response["issueCreate"]["issue"]
+                log_info(f"Issue '{issue['title']}' created successfully with ID {issue['id']}")
+                return str(issue)
+            else:
+                logger.error("Issue creation failed.")
+                return None
+
+        except Exception as e:
+            logger.error(f"Error creating issue '{title}' for team ID {team_id}: {e}")
+            raise
+
+    def update_issue(self, issue_id: str, title: Optional[str]) -> Optional[str]:
+        """
+        Update the title or state of a specific issue by issue ID.
+
+        Args:
+            issue_id (str): The unique identifier of the issue to update.
+            title (str, optional): The new title for the issue. If None, the title remains unchanged.
+
+        Returns:
+            str or None: A string containing the updated issue's details with issue id, issue title, and issue state (which includes `id` and `name`).
+                  Returns `None` if the update is unsuccessful.
+
+        Raises:
+            Exception: If an error occurs during the mutation execution or data retrieval.
+        """
+
+        query = """
+        mutation IssueUpdate ($issueId: String!, $title: String!){
+          issueUpdate(
+            id: $issueId,
+            input: { title: $title}
+          ) {
+            success
+            issue {
+              id
+              title
+              state {
+                id
+                name
+              }
+            }
+          }
+        }
+        """
+        variables = {"issueId": issue_id, "title": title}
+
+        try:
+            response = self._execute_query(query, variables)
+
+            if response["issueUpdate"]["success"]:
+                issue = response["issueUpdate"]["issue"]
+                log_info(f"Issue ID {issue_id} updated successfully.")
+                return str(issue)
+            else:
+                logger.error(f"Failed to update issue ID {issue_id}. Success flag was false.")
+                return None
+
+        except Exception as e:
+            logger.error(f"Error updating issue ID {issue_id}: {e}")
+            raise
+
+    def get_user_assigned_issues(self, user_id: str) -> Optional[str]:
+        """
+        Retrieve issues assigned to a specific user by user ID.
+
+        Args:
+            user_id (str): The unique identifier of the user for whom to retrieve assigned issues.
+
+        Returns:
+            str or None: A string representing the assigned issues to user id,
+            where each issue contains issue details (e.g., `id`, `title`).
+            Returns None if the user or issues cannot be retrieved.
+
+        Raises:
+            Exception: If an error occurs while querying for the user's assigned issues.
+        """
+
+        query = """
+        query UserAssignedIssues($userId: String!) {
+        user(id: $userId) {
+          id
+          name
+          assignedIssues {
+            nodes {
+              id
+              title
+              }
+            }
+          }
+        }
+        """
+        variables = {"userId": user_id}
+
+        try:
+            response = self._execute_query(query, variables)
+
+            if response.get("user"):
+                user = response["user"]
+                issues = user["assignedIssues"]["nodes"]
+                log_info(f"Retrieved {len(issues)} issues assigned to user '{user['name']}' (ID: {user['id']}).")
+                return str(issues)
+            else:
+                logger.error("Failed to retrieve user or issues.")
+                return None
+
+        except Exception as e:
+            logger.error(f"Error retrieving issues for user ID {user_id}: {e}")
+            raise
+
+    def get_workflow_issues(self, workflow_id: str) -> Optional[str]:
+        """
+        Retrieve issues within a specific workflow state by workflow ID.
+
+        Args:
+            workflow_id (str): The unique identifier of the workflow state to retrieve issues from.
+
+        Returns:
+            str or None: A string representing the issues within the specified workflow state,
+            where each issue contains details of an issue (e.g., `title`).
+            Returns None if no issues are found or if the workflow state cannot be retrieved.
+
+        Raises:
+            Exception: If an error occurs while querying issues for the specified workflow state.
+        """
+
+        query = """
+        query WorkflowStateIssues($workflowId: String!) {
+        workflowState(id: $workflowId) {
+          issues {
+            nodes {
+              title
+              }
+            }
+          }
+        }
+        """
+        variables = {"workflowId": workflow_id}
+        try:
+            response = self._execute_query(query, variables)
+
+            if response.get("workflowState"):
+                issues = response["workflowState"]["issues"]["nodes"]
+                log_info(f"Retrieved {len(issues)} issues in workflow state ID {workflow_id}.")
+                return str(issues)
+            else:
+                logger.error("Failed to retrieve issues for the specified workflow state.")
+                return None
+
+        except Exception as e:
+            logger.error(f"Error retrieving issues for workflow state ID {workflow_id}: {e}")
+            raise
+
+    def get_high_priority_issues(self) -> Optional[str]:
+        """
+        Retrieve issues with a high priority (priority <= 2).
+
+        Returns:
+            str or None: A str representing high-priority issues, where it
+            contains details of an issue (e.g., `id`, `title`, `priority`).
+            Returns None if no issues are retrieved.
+
+        Raises:
+            Exception: If an error occurs during the query process.
+        """
+
+        query = """
+        query HighPriorityIssues {
+        issues(filter: {
+          priority: { lte: 2 }
+        }) {
+          nodes {
+            id
+            title
+            priority
+            }
+          }
+        }
+        """
+        try:
+            response = self._execute_query(query)
+
+            if response.get("issues"):
+                high_priority_issues = response["issues"]["nodes"]
+                log_info(f"Retrieved {len(high_priority_issues)} high-priority issues.")
+                return str(high_priority_issues)
+            else:
+                logger.error("Failed to retrieve high-priority issues.")
+                return None
+
+        except Exception as e:
+            logger.error(f"Error retrieving high-priority issues: {e}")
+            raise

agno/tools/linkup.py

@@ -0,0 +1,58 @@
+from os import getenv
+from typing import Any, List, Literal, Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import logger
+
+try:
+    from linkup import LinkupClient
+except ImportError:
+    raise ImportError("`linkup-sdk` not installed. Please install using `pip install linkup-sdk`")
+
+
+class LinkupTools(Toolkit):
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        depth: Literal["standard", "deep"] = "standard",
+        output_type: Literal["sourcedAnswer", "searchResults"] = "searchResults",
+        enable_web_search_with_linkup: bool = True,
+        all: bool = False,
+        **kwargs,
+    ):
+        self.api_key = api_key or getenv("LINKUP_API_KEY")
+        if not self.api_key:
+            logger.error("LINKUP_API_KEY not set. Please set the LINKUP_API_KEY environment variable.")
+
+        self.linkup = LinkupClient(api_key=api_key)
+        self.depth = depth
+        self.output_type = output_type
+
+        tools: List[Any] = []
+        if all or enable_web_search_with_linkup:
+            tools.append(self.web_search_with_linkup)
+
+        super().__init__(name="linkup_tools", tools=tools, **kwargs)
+
+    def web_search_with_linkup(self, query: str, depth: Optional[str] = None, output_type: Optional[str] = None) -> str:
+        """
+        Use this function to search the web for a given query.
+        This function uses the Linkup API to provide realtime online information about the query.
+
+        Args:
+            query (str): Query to search for.
+            depth (str): (deep|standard) Depth of the search. Defaults to 'standard'.
+            output_type (str): (sourcedAnswer|searchResults) Type of output. Defaults to 'searchResults'.
+
+        Returns:
+            str: string of results related to the query.
+        """
+        try:
+            response = self.linkup.search(
+                query=query,
+                depth=depth or self.depth,  # type: ignore
+                output_type=output_type or self.output_type,  # type: ignore
+            )
+            return response
+        except Exception as e:
+            return f"Error: {str(e)}"

agno/tools/local_file_system.py

@@ -0,0 +1,90 @@
+from pathlib import Path
+from typing import Optional
+from uuid import uuid4
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, logger
+
+
+class LocalFileSystemTools(Toolkit):
+    def __init__(
+        self,
+        target_directory: Optional[str] = None,
+        default_extension: str = "txt",
+        enable_write_file: bool = True,
+        all: bool = False,
+        **kwargs,
+    ):
+        """
+        Initialize the WriteToLocal toolkit.
+        Args:
+            target_directory (Optional[str]): Default directory to write files to. Creates if doesn't exist.
+            default_extension (str): Default file extension to use if none specified.
+        """
+
+        self.target_directory = target_directory or str(Path.cwd())
+        self.default_extension = default_extension.lstrip(".")
+
+        target_path = Path(self.target_directory)
+        target_path.mkdir(parents=True, exist_ok=True)
+
+        tools = []
+        if all or enable_write_file:
+            tools.append(self.write_file)
+
+        super().__init__(name="write_to_local", tools=tools, **kwargs)
+
+    def write_file(
+        self,
+        content: str,
+        filename: Optional[str] = None,
+        directory: Optional[str] = None,
+        extension: Optional[str] = None,
+    ) -> str:
+        """
+        Write content to a local file.
+        Args:
+            content (str): Content to write to the file
+            filename (Optional[str]): Name of the file. Defaults to UUID if not provided
+            directory (Optional[str]): Directory to write file to. Uses target_directory if not provided
+            extension (Optional[str]): File extension. Uses default_extension if not provided
+        Returns:
+            str: Path to the created file or error message
+        """
+        try:
+            filename = filename or str(uuid4())
+            directory = directory or self.target_directory
+            if filename and "." in filename:
+                path_obj = Path(filename)
+                filename = path_obj.stem
+                extension = extension or path_obj.suffix.lstrip(".")
+
+            log_debug(f"Writing file to local system: {filename}")
+
+            extension = (extension or self.default_extension).lstrip(".")
+
+            # Create directory if it doesn't exist
+            dir_path = Path(directory)
+            dir_path.mkdir(parents=True, exist_ok=True)
+
+            # Construct full filename with extension
+            full_filename = f"{filename}.{extension}"
+            file_path = dir_path / full_filename
+
+            file_path.write_text(content)
+
+            return f"Successfully wrote file to: {file_path}"
+
+        except Exception as e:
+            error_msg = f"Failed to write file: {str(e)}"
+            logger.error(error_msg)
+            return f"Error: {error_msg}"
+
+    def read_file(self, filename: str, directory: Optional[str] = None) -> str:
+        """
+        Read content from a local file.
+        """
+        file_path = Path(directory or self.target_directory) / filename
+        if not file_path.exists():
+            return f"File not found: {file_path}"
+        return file_path.read_text()