agno 2.2.13__py3-none-any.whl

agno/tools/jira.py

@@ -0,0 +1,170 @@
+import json
+from os import getenv
+from typing import Any, List, Optional, cast
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, logger
+
+try:
+    from jira import JIRA, Issue
+except ImportError:
+    raise ImportError("`jira` not installed. Please install using `pip install jira`")
+
+
+class JiraTools(Toolkit):
+    def __init__(
+        self,
+        server_url: Optional[str] = None,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        token: Optional[str] = None,
+        enable_get_issue: bool = True,
+        enable_create_issue: bool = True,
+        enable_search_issues: bool = True,
+        enable_add_comment: bool = True,
+        enable_add_worklog: bool = True,
+        all: bool = False,
+        **kwargs,
+    ):
+        self.server_url = server_url or getenv("JIRA_SERVER_URL")
+        self.username = username or getenv("JIRA_USERNAME")
+        self.password = password or getenv("JIRA_PASSWORD")
+        self.token = token or getenv("JIRA_TOKEN")
+
+        if not self.server_url:
+            raise ValueError("JIRA server URL not provided.")
+
+        # Initialize JIRA client
+        if self.token and self.username:
+            auth = (self.username, self.token)
+        elif self.username and self.password:
+            auth = (self.username, self.password)
+        else:
+            auth = None
+
+        if auth:
+            self.jira = JIRA(server=self.server_url, basic_auth=cast(tuple[str, str], auth))
+        else:
+            self.jira = JIRA(server=self.server_url)
+
+        tools: List[Any] = []
+        if enable_get_issue or all:
+            tools.append(self.get_issue)
+        if enable_create_issue or all:
+            tools.append(self.create_issue)
+        if enable_search_issues or all:
+            tools.append(self.search_issues)
+        if enable_add_comment or all:
+            tools.append(self.add_comment)
+        if enable_add_worklog or all:
+            tools.append(self.add_worklog)
+
+        super().__init__(name="jira_tools", tools=tools, **kwargs)
+
+    def get_issue(self, issue_key: str) -> str:
+        """
+        Retrieves issue details from Jira.
+
+        :param issue_key: The key of the issue to retrieve.
+        :return: A JSON string containing issue details.
+        """
+        try:
+            issue = self.jira.issue(issue_key)
+            issue = cast(Issue, issue)
+            issue_details = {
+                "key": issue.key,
+                "project": issue.fields.project.key,
+                "issuetype": issue.fields.issuetype.name,
+                "reporter": issue.fields.reporter.displayName if issue.fields.reporter else "N/A",
+                "summary": issue.fields.summary,
+                "description": issue.fields.description or "",
+            }
+            log_debug(f"Issue details retrieved for {issue_key}: {issue_details}")
+            return json.dumps(issue_details)
+        except Exception as e:
+            logger.error(f"Error retrieving issue {issue_key}: {e}")
+            return json.dumps({"error": str(e)})
+
+    def create_issue(self, project_key: str, summary: str, description: str, issuetype: str = "Task") -> str:
+        """
+        Creates a new issue in Jira.
+
+        :param project_key: The key of the project in which to create the issue.
+        :param summary: The summary of the issue.
+        :param description: The description of the issue.
+        :param issuetype: The type of issue to create.
+        :return: A JSON string with the new issue's key and URL.
+        """
+        try:
+            issue_dict = {
+                "project": {"key": project_key},
+                "summary": summary,
+                "description": description,
+                "issuetype": {"name": issuetype},
+            }
+            new_issue = self.jira.create_issue(fields=issue_dict)
+            issue_url = f"{self.server_url}/browse/{new_issue.key}"
+            log_debug(f"Issue created with key: {new_issue.key}")
+            return json.dumps({"key": new_issue.key, "url": issue_url})
+        except Exception as e:
+            logger.error(f"Error creating issue in project {project_key}: {e}")
+            return json.dumps({"error": str(e)})
+
+    def search_issues(self, jql_str: str, max_results: int = 50) -> str:
+        """
+        Searches for issues using a JQL query.
+
+        :param jql_str: The JQL query string.
+        :param max_results: Maximum number of results to return.
+        :return: A JSON string containing a list of dictionaries with issue details.
+        """
+        try:
+            issues = self.jira.search_issues(jql_str, maxResults=max_results)
+            results = []
+            for issue in issues:
+                issue = cast(Issue, issue)
+                issue_details = {
+                    "key": issue.key,
+                    "summary": issue.fields.summary,
+                    "status": issue.fields.status.name,
+                    "assignee": issue.fields.assignee.displayName if issue.fields.assignee else "Unassigned",
+                }
+                results.append(issue_details)
+            log_debug(f"Found {len(results)} issues for JQL '{jql_str}'")
+            return json.dumps(results)
+        except Exception as e:
+            logger.error(f"Error searching issues with JQL '{jql_str}': {e}")
+            return json.dumps([{"error": str(e)}])
+
+    def add_comment(self, issue_key: str, comment: str) -> str:
+        """
+        Adds a comment to an issue.
+
+        :param issue_key: The key of the issue.
+        :param comment: The comment text.
+        :return: A JSON string indicating success or containing an error message.
+        """
+        try:
+            self.jira.add_comment(issue_key, comment)
+            log_debug(f"Comment added to issue {issue_key}")
+            return json.dumps({"status": "success", "issue_key": issue_key})
+        except Exception as e:
+            logger.error(f"Error adding comment to issue {issue_key}: {e}")
+            return json.dumps({"error": str(e)})
+
+    def add_worklog(self, issue_key: str, time_spent: str, comment: Optional[str] = None) -> str:
+        """
+        Adds a worklog entry to log time spent on a specific Jira issue.
+
+        :param issue_key: The key of the issue to log work against (e.g., 'PROJ-123').
+        :param time_spent: The amount of time spent. Use Jira's format, e.g., '2h', '30m', '1d 4h'.
+        :param comment: An optional comment describing the work done.
+        :return: A JSON string indicating success or containing an error message.
+        """
+        try:
+            self.jira.add_worklog(issue=issue_key, timeSpent=time_spent, comment=comment)
+            log_debug(f"Worklog of '{time_spent}' added to issue {issue_key}")
+            return json.dumps({"status": "success", "issue_key": issue_key, "time_spent": time_spent})
+        except Exception as e:
+            logger.error(f"Error adding worklog to issue {issue_key}: {e}")
+            return json.dumps({"error": str(e)})

agno/tools/knowledge.py

@@ -0,0 +1,218 @@
+import json
+from textwrap import dedent
+from typing import Any, Dict, List, Optional
+
+from agno.knowledge.document import Document
+from agno.knowledge.knowledge import Knowledge
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, log_error
+
+
+class KnowledgeTools(Toolkit):
+    def __init__(
+        self,
+        knowledge: Knowledge,
+        enable_think: bool = True,
+        enable_search: bool = True,
+        enable_analyze: bool = True,
+        instructions: Optional[str] = None,
+        add_instructions: bool = True,
+        add_few_shot: bool = False,
+        few_shot_examples: Optional[str] = None,
+        all: bool = False,
+        **kwargs,
+    ):
+        if knowledge is None:
+            raise ValueError("knowledge must be provided when using KnowledgeTools")
+
+        # Add instructions for using this toolkit
+        if instructions is None:
+            self.instructions = self.DEFAULT_INSTRUCTIONS
+            if add_few_shot:
+                if few_shot_examples is not None:
+                    self.instructions += "\n" + few_shot_examples
+                else:
+                    self.instructions += "\n" + self.FEW_SHOT_EXAMPLES
+        else:
+            self.instructions = instructions
+
+        # The knowledge to search
+        self.knowledge: Knowledge = knowledge
+
+        tools: List[Any] = []
+        if enable_think or all:
+            tools.append(self.think)
+        if enable_search or all:
+            tools.append(self.search_knowledge)
+        if enable_analyze or all:
+            tools.append(self.analyze)
+
+        super().__init__(
+            name="knowledge_tools",
+            tools=tools,
+            instructions=self.instructions,
+            add_instructions=add_instructions,
+            **kwargs,
+        )
+
+    def think(self, session_state: Dict[str, Any], thought: str) -> str:
+        """Use this tool as a scratchpad to reason about the question, refine your approach, brainstorm search terms, or revise your plan.
+
+        Call `Think` whenever you need to figure out what to do next, analyze the user's question, or plan your approach.
+        You should use this tool as frequently as needed.
+
+        Args:
+            thought: Your thought process and reasoning.
+
+        Returns:
+            str: The full log of reasoning and the new thought.
+        """
+        try:
+            log_debug(f"Thought: {thought}")
+
+            # Add the thought to the Agent state
+            if session_state is None:
+                session_state = {}
+            if "thoughts" not in session_state:
+                session_state["thoughts"] = []
+            session_state["thoughts"].append(thought)
+
+            # Return the full log of thoughts and the new thought
+            thoughts = "\n".join([f"- {t}" for t in session_state["thoughts"]])
+            formatted_thoughts = dedent(
+                f"""Thoughts:
+                {thoughts}
+                """
+            ).strip()
+            return formatted_thoughts
+        except Exception as e:
+            log_error(f"Error recording thought: {e}")
+            return f"Error recording thought: {e}"
+
+    def search_knowledge(self, session_state: Dict[str, Any], query: str) -> str:
+        """Use this tool to search the knowledge base for relevant information.
+        After thinking through the question, use this tool as many times as needed to search for relevant information.
+
+        Args:
+            query: The query to search the knowledge base for.
+
+        Returns:
+            str: A string containing the response from the knowledge base.
+        """
+        try:
+            log_debug(f"Searching knowledge base: {query}")
+
+            # Get the relevant documents from the knowledge base
+            relevant_docs: List[Document] = self.knowledge.search(query=query)
+            if len(relevant_docs) == 0:
+                return "No documents found"
+            return json.dumps([doc.to_dict() for doc in relevant_docs])
+        except Exception as e:
+            log_error(f"Error searching knowledge base: {e}")
+            return f"Error searching knowledge base: {e}"
+
+    def analyze(self, session_state: Dict[str, Any], analysis: str) -> str:
+        """Use this tool to evaluate whether the returned documents are correct and sufficient.
+        If not, go back to "Think" or "Search" with refined queries.
+
+        Args:
+            analysis: A thought to think about and log.
+
+        Returns:
+            str: The full log of thoughts and the new thought.
+        """
+        try:
+            log_debug(f"Analysis: {analysis}")
+
+            # Add the thought to the Agent state
+            if session_state is None:
+                session_state = {}
+            if "analysis" not in session_state:
+                session_state["analysis"] = []
+            session_state["analysis"].append(analysis)
+
+            # Return the full log of thoughts and the new thought
+            analysis = "\n".join([f"- {a}" for a in session_state["analysis"]])
+            formatted_analysis = dedent(
+                f"""Analysis:
+                {analysis}
+                """
+            ).strip()
+            return formatted_analysis
+        except Exception as e:
+            log_error(f"Error recording analysis: {e}")
+            return f"Error recording analysis: {e}"
+
+    DEFAULT_INSTRUCTIONS = dedent("""\
+        You have access to the Think, Search, and Analyze tools that will help you search your knowledge for relevant information. Use these tools as frequently as needed to find the most relevant information.
+
+        ## How to use the Think, Search, and Analyze tools:
+        1. **Think**
+        - Purpose: A scratchpad for planning, brainstorming keywords, and refining your approach. You never reveal your "Think" content to the user.
+        - Usage: Call `think` whenever you need to figure out what to do next, analyze your approach, or decide new search terms before (or after) you look up documents.
+
+        2. **Search**
+        - Purpose: Executes a query against the knowledge base.
+        - Usage: Call `search` with a clear query string whenever you want to retrieve documents or data. You can and should call this tool multiple times in one conversation.
+            - For complex topics, use multiple focused searches rather than one broad search
+            - Try different phrasing and keywords if initial searches don't yield useful results
+            - Use quotes for exact phrases and OR for alternative terms (e.g., "protein synthesis" OR "protein formation")
+
+        3. **Analyze**
+        - Purpose: Evaluate whether the returned documents are correct and sufficient. If not, go back to "Think" or "Search" with refined queries.
+        - Usage: Call `analyze` after getting search results to verify the quality and correctness of that information. Consider:
+            - Relevance: Do the documents directly address the user's question?
+            - Completeness: Is there enough information to provide a thorough answer?
+            - Reliability: Are the sources credible and up-to-date?
+            - Consistency: Do the documents agree or contradict each other?
+
+        **Important Guidelines**:
+        - Do not include your internal chain-of-thought in direct user responses.
+        - Use "Think" to reason internally. These notes are never exposed to the user.
+        - Iterate through the cycle (Think → Search → Analyze) as many times as needed until you have a final answer.
+        - When you do provide a final answer to the user, be clear, concise, and accurate.
+        - If search results are sparse or contradictory, acknowledge limitations in your response.
+        - Synthesize information from multiple sources rather than relying on a single document.\
+    """)
+
+    FEW_SHOT_EXAMPLES = dedent("""\
+        You can refer to the examples below as guidance for how to use each tool.
+        ### Examples
+
+        #### Example 1: Multiple Searches and Analysis
+
+        User: What are the recommended dietary guidelines for someone with mild hypertension?
+        Think: The user is asking about dietary guidelines for mild hypertension. I'll start broad, then refine if needed.
+        Search: "dietary guidelines for mild hypertension", "salt intake recommendations for mild hypertension"
+        Analyze: I got one document referencing the DASH diet, but it's quite brief. I might need more info about salt intake recommendations specifically.
+        Think: Let me refine my search to see if there are official guidelines from recognized health organizations.
+        Search: "WHO or American Heart Association guidelines for hypertension", "fruits and vegetables for mild hypertension"
+        Analyze: The new documents mention daily sodium limits, recommended fruit/vegetable intake, and more. This seems thorough. I'm ready to formulate the answer.
+
+        Final Answer: For mild hypertension, the guidelines typically recommend following the DASH diet, which emphasizes ...
+
+        #### Example 2: Invalid or Insufficient Search Results
+
+        User: Do you have any documentation on the 'XYZ Project' from last year?
+        Think: I'll try searching for 'XYZ Project last year' but if that fails, I'll look for internal code names or older references.
+        Search: "XYZ Project last year"
+        Analyze: No relevant documents. Let me refine my search to check for 'XYZ Project' in different date ranges or alternate titles.
+        Think: Possibly it's under 'XYZ Initiative' or 'XYZ Rollout.' Let's do a second search.
+        Search: "XYZ Initiative OR 'XYZ Rollout' from last year"
+        Analyze: Found a relevant archive for 'XYZ Initiative'. Looks correct and references last year's timeline. I'll proceed with that info.
+
+        Final Answer: Yes, we have some archived documentation under the name 'XYZ Initiative.' It includes ...
+
+        #### Example 3: Synthesizing Complex Information
+
+        User: How do quantum computers differ from classical computers in terms of performance?
+        Think: This is a technical question requiring clear explanations of quantum vs. classical computing performance characteristics.
+        Search: "quantum computing performance vs classical computing"
+        Analyze: Found general information but need more specifics on actual performance metrics and use cases.
+        Think: Let me search for specific quantum advantages and limitations.
+        Search: "quantum supremacy examples", "quantum computing limitations"
+        Search: "quantum computing speedup for specific algorithms"
+        Analyze: Now I have concrete examples of quantum speedup for certain algorithms, limitations for others, and real-world benchmarks.
+
+        Final Answer: Quantum computers differ from classical computers in three key ways: [synthesized explanation with specific examples]...\
+    """)