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

agno/tools/python.py

@@ -1,10 +1,10 @@
 import functools
 import runpy
 from pathlib import Path
-from typing import Optional
+from typing import Any, List, Optional
 
 from agno.tools import Toolkit
-from agno.utils.log import logger
+from agno.utils.log import log_debug, log_info, logger
 
 
 @functools.lru_cache(maxsize=None)
@@ -16,35 +16,27 @@ class PythonTools(Toolkit):
     def __init__(
         self,
         base_dir: Optional[Path] = None,
-        save_and_run: bool = True,
-        pip_install: bool = False,
-        run_code: bool = False,
-        list_files: bool = False,
-        run_files: bool = False,
-        read_files: bool = False,
         safe_globals: Optional[dict] = None,
         safe_locals: Optional[dict] = None,
+        **kwargs,
     ):
-        super().__init__(name="python_tools")
-
         self.base_dir: Path = base_dir or Path.cwd()
 
         # Restricted global and local scope
         self.safe_globals: dict = safe_globals or globals()
         self.safe_locals: dict = safe_locals or locals()
 
-        if run_code:
-            self.register(self.run_python_code, sanitize_arguments=False)
-        if save_and_run:
-            self.register(self.save_to_file_and_run, sanitize_arguments=False)
-        if pip_install:
-            self.register(self.pip_install_package)
-        if run_files:
-            self.register(self.run_python_file_return_variable)
-        if read_files:
-            self.register(self.read_file)
-        if list_files:
-            self.register(self.list_files)
+        tools: List[Any] = [
+            self.save_to_file_and_run,
+            self.run_python_code,
+            self.pip_install_package,
+            self.uv_pip_install_package,
+            self.run_python_file_return_variable,
+            self.read_file,
+            self.list_files,
+        ]
+
+        super().__init__(name="python_tools", tools=tools, **kwargs)
 
     def save_to_file_and_run(
         self, file_name: str, code: str, variable_to_return: Optional[str] = None, overwrite: bool = True
@@ -64,21 +56,21 @@ class PythonTools(Toolkit):
         try:
             warn()
             file_path = self.base_dir.joinpath(file_name)
-            logger.debug(f"Saving code to {file_path}")
+            log_debug(f"Saving code to {file_path}")
             if not file_path.parent.exists():
                 file_path.parent.mkdir(parents=True, exist_ok=True)
             if file_path.exists() and not overwrite:
                 return f"File {file_name} already exists"
-            file_path.write_text(code)
-            logger.info(f"Saved: {file_path}")
-            logger.info(f"Running {file_path}")
+            file_path.write_text(code, encoding="utf-8")
+            log_info(f"Saved: {file_path}")
+            log_info(f"Running {file_path}")
             globals_after_run = runpy.run_path(str(file_path), init_globals=self.safe_globals, run_name="__main__")
 
             if variable_to_return:
                 variable_value = globals_after_run.get(variable_to_return)
                 if variable_value is None:
                     return f"Variable {variable_to_return} not found"
-                logger.debug(f"Variable {variable_to_return} value: {variable_value}")
+                log_debug(f"Variable {variable_to_return} value: {variable_value}")
                 return str(variable_value)
             else:
                 return f"successfully ran {str(file_path)}"
@@ -99,13 +91,13 @@ class PythonTools(Toolkit):
             warn()
             file_path = self.base_dir.joinpath(file_name)
 
-            logger.info(f"Running {file_path}")
+            log_info(f"Running {file_path}")
             globals_after_run = runpy.run_path(str(file_path), init_globals=self.safe_globals, run_name="__main__")
             if variable_to_return:
                 variable_value = globals_after_run.get(variable_to_return)
                 if variable_value is None:
                     return f"Variable {variable_to_return} not found"
-                logger.debug(f"Variable {variable_to_return} value: {variable_value}")
+                log_debug(f"Variable {variable_to_return} value: {variable_value}")
                 return str(variable_value)
             else:
                 return f"successfully ran {str(file_path)}"
@@ -120,9 +112,9 @@ class PythonTools(Toolkit):
         :return: The contents of the file if successful, otherwise returns an error message.
         """
         try:
-            logger.info(f"Reading file: {file_name}")
+            log_info(f"Reading file: {file_name}")
             file_path = self.base_dir.joinpath(file_name)
-            contents = file_path.read_text()
+            contents = file_path.read_text(encoding="utf-8")
             return str(contents)
         except Exception as e:
             logger.error(f"Error reading file: {e}")
@@ -134,7 +126,7 @@ class PythonTools(Toolkit):
         :return: Comma separated list of files in the base directory.
         """
         try:
-            logger.info(f"Reading files in : {self.base_dir}")
+            log_info(f"Reading files in : {self.base_dir}")
             files = [str(file_path.name) for file_path in self.base_dir.iterdir()]
             return ", ".join(files)
         except Exception as e:
@@ -155,14 +147,14 @@ class PythonTools(Toolkit):
         try:
             warn()
 
-            logger.debug(f"Running code:\n\n{code}\n\n")
+            log_debug(f"Running code:\n\n{code}\n\n")
             exec(code, self.safe_globals, self.safe_locals)
 
             if variable_to_return:
                 variable_value = self.safe_locals.get(variable_to_return)
                 if variable_value is None:
                     return f"Variable {variable_to_return} not found"
-                logger.debug(f"Variable {variable_to_return} value: {variable_value}")
+                log_debug(f"Variable {variable_to_return} value: {variable_value}")
                 return str(variable_value)
             else:
                 return "successfully ran python code"
@@ -181,7 +173,7 @@ class PythonTools(Toolkit):
         try:
             warn()
 
-            logger.debug(f"Installing package {package_name}")
+            log_debug(f"Installing package {package_name}")
             import subprocess
             import sys
 
@@ -190,3 +182,24 @@ class PythonTools(Toolkit):
         except Exception as e:
             logger.error(f"Error installing package {package_name}: {e}")
             return f"Error installing package {package_name}: {e}"
+
+    def uv_pip_install_package(self, package_name: str) -> str:
+        """This function installs a package using uv and pip in the current environment.
+        If successful, returns a success message.
+        If failed, returns an error message.
+
+        :param package_name: The name of the package to install.
+        :return: success message if successful, otherwise returns an error message.
+        """
+        try:
+            warn()
+
+            log_debug(f"Installing package {package_name}")
+            import subprocess
+            import sys
+
+            subprocess.check_call([sys.executable, "-m", "uv", "pip", "install", package_name])
+            return f"successfully installed package {package_name}"
+        except Exception as e:
+            logger.error(f"Error installing package {package_name}: {e}")
+            return f"Error installing package {package_name}: {e}"

agno/tools/reasoning.py

@@ -0,0 +1,283 @@
+from textwrap import dedent
+from typing import Any, Dict, List, Optional
+
+from agno.reasoning.step import NextAction, ReasoningStep
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, log_error
+
+
+class ReasoningTools(Toolkit):
+    def __init__(
+        self,
+        enable_think: bool = True,
+        enable_analyze: bool = True,
+        all: bool = False,
+        instructions: Optional[str] = None,
+        add_instructions: bool = False,
+        add_few_shot: bool = False,
+        few_shot_examples: Optional[str] = None,
+        **kwargs,
+    ):
+        """A toolkit that provides step-by-step reasoning tools: Think and Analyze."""
+
+        # Add instructions for using this toolkit
+        if instructions is None:
+            self.instructions = "<reasoning_instructions>\n" + 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
+            self.instructions += "\n</reasoning_instructions>\n"
+        else:
+            self.instructions = instructions
+
+        tools: List[Any] = []
+        # Prefer new flags; fallback to legacy ones
+        if all or enable_think:
+            tools.append(self.think)
+        if all or enable_analyze:
+            tools.append(self.analyze)
+
+        super().__init__(
+            name="reasoning_tools",
+            instructions=self.instructions,
+            add_instructions=add_instructions,
+            tools=tools,
+            **kwargs,
+        )
+
+    def think(
+        self,
+        session_state: Dict[str, Any],
+        title: str,
+        thought: str,
+        action: Optional[str] = None,
+        confidence: float = 0.8,
+    ) -> str:
+        """Use this tool as a scratchpad to reason about the question and work through it step-by-step.
+        This tool will help you break down complex problems into logical steps and track the reasoning process.
+        You can call it as many times as needed. These internal thoughts are never revealed to the user.
+
+        Args:
+            title: A concise title for this step
+            thought: Your detailed thought for this step
+            action: What you'll do based on this thought
+            confidence: How confident you are about this thought (0.0 to 1.0)
+
+        Returns:
+            A list of previous thoughts and the new thought
+        """
+        try:
+            log_debug(f"Thought about {title}")
+
+            # Create a reasoning step
+            reasoning_step = ReasoningStep(
+                title=title,
+                reasoning=thought,
+                action=action,
+                next_action=NextAction.CONTINUE,
+                confidence=confidence,
+            )
+
+            current_run_id = session_state.get("current_run_id", None)
+
+            # Add this step to the Agent's session state
+            if session_state is None:
+                session_state = {}
+            if "reasoning_steps" not in session_state:
+                session_state["reasoning_steps"] = {}
+            if current_run_id not in session_state["reasoning_steps"]:
+                session_state["reasoning_steps"][current_run_id] = []
+            session_state["reasoning_steps"][current_run_id].append(reasoning_step.model_dump_json())
+
+            # Return all previous reasoning_steps and the new reasoning_step
+            if "reasoning_steps" in session_state and current_run_id in session_state["reasoning_steps"]:
+                formatted_reasoning_steps = ""
+                for i, step in enumerate(session_state["reasoning_steps"][current_run_id], 1):
+                    step_parsed = ReasoningStep.model_validate_json(step)
+                    step_str = dedent(f"""\
+Step {i}:
+Title: {step_parsed.title}
+Reasoning: {step_parsed.reasoning}
+Action: {step_parsed.action}
+Confidence: {step_parsed.confidence}
+""")
+                    formatted_reasoning_steps += step_str + "\n"
+                return formatted_reasoning_steps.strip()
+            return reasoning_step.model_dump_json()
+        except Exception as e:
+            log_error(f"Error recording thought: {e}")
+            return f"Error recording thought: {e}"
+
+    def analyze(
+        self,
+        session_state: Dict[str, Any],
+        title: str,
+        result: str,
+        analysis: str,
+        next_action: str = "continue",
+        confidence: float = 0.8,
+    ) -> str:
+        """Use this tool to analyze results from a reasoning step and determine next actions.
+
+        Args:
+            title: A concise title for this analysis step
+            result: The outcome of the previous action
+            analysis: Your analysis of the results
+            next_action: What to do next ("continue", "validate", or "final_answer")
+            confidence: How confident you are in this analysis (0.0 to 1.0)
+
+        Returns:
+            A list of previous thoughts and the new analysis
+        """
+        try:
+            log_debug(f"Analyzed {title}")
+
+            # Map string next_action to enum
+            next_action_enum = NextAction.CONTINUE
+            if next_action.lower() == "validate":
+                next_action_enum = NextAction.VALIDATE
+            elif next_action.lower() in ["final", "final_answer", "finalize"]:
+                next_action_enum = NextAction.FINAL_ANSWER
+
+            # Create a reasoning step for the analysis
+            reasoning_step = ReasoningStep(
+                title=title,
+                result=result,
+                reasoning=analysis,
+                next_action=next_action_enum,
+                confidence=confidence,
+            )
+
+            current_run_id = session_state.get("current_run_id", None)
+            # Add this step to the Agent's session state
+            if session_state is None:
+                session_state = {}
+            if "reasoning_steps" not in session_state:
+                session_state["reasoning_steps"] = {}
+            if current_run_id not in session_state["reasoning_steps"]:
+                session_state["reasoning_steps"][current_run_id] = []
+            session_state["reasoning_steps"][current_run_id].append(reasoning_step.model_dump_json())
+
+            # Return all previous reasoning_steps and the new reasoning_step
+            if "reasoning_steps" in session_state and current_run_id in session_state["reasoning_steps"]:
+                formatted_reasoning_steps = ""
+                for i, step in enumerate(session_state["reasoning_steps"][current_run_id], 1):
+                    step_parsed = ReasoningStep.model_validate_json(step)
+                    step_str = dedent(f"""\
+Step {i}:
+Title: {step_parsed.title}
+Reasoning: {step_parsed.reasoning}
+Action: {step_parsed.action}
+Confidence: {step_parsed.confidence}
+""")
+                    formatted_reasoning_steps += step_str + "\n"
+                return formatted_reasoning_steps.strip()
+            return reasoning_step.model_dump_json()
+        except Exception as e:
+            log_error(f"Error recording analysis: {e}")
+            return f"Error recording analysis: {e}"
+
+    # --------------------------------------------------------------------------------
+    # Default instructions and few-shot examples
+    # --------------------------------------------------------------------------------
+
+    DEFAULT_INSTRUCTIONS = dedent(
+        """\
+        You have access to the `think` and `analyze` tools to work through problems step-by-step and structure your thought process. You must ALWAYS `think` before making tool calls or generating a response.
+
+        1. **Think** (scratchpad):
+            - Purpose: Use the `think` tool as a scratchpad to break down complex problems, outline steps, and decide on immediate actions within your reasoning flow. Use this to structure your internal monologue.
+            - Usage: Call `think` before making tool calls or generating a response. Explain your reasoning and specify the intended action (e.g., "make a tool call", "perform calculation", "ask clarifying question").
+
+        2. **Analyze** (evaluation):
+            - Purpose: Evaluate the result of a think step or a set of tool calls. Assess if the result is expected, sufficient, or requires further investigation.
+            - Usage: Call `analyze` after a set of tool calls. Determine the `next_action` based on your analysis: `continue` (more reasoning needed), `validate` (seek external confirmation/validation if possible), or `final_answer` (ready to conclude).
+            - Explain your reasoning highlighting whether the result is correct/sufficient.
+
+        ## IMPORTANT GUIDELINES
+        - **Always Think First:** You MUST use the `think` tool before making tool calls or generating a response.
+        - **Iterate to Solve:** Use the `think` and `analyze` tools iteratively to build a clear reasoning path. The typical flow is `Think` -> [`Tool Calls` if needed] -> [`Analyze` if needed] -> ... -> `final_answer`. Repeat this cycle until you reach a satisfactory conclusion.
+        - **Make multiple tool calls in parallel:** After a `think` step, you can make multiple tool calls in parallel.
+        - **Keep Thoughts Internal:** The reasoning steps (thoughts and analyses) are for your internal process only. Do not share them directly with the user.
+        - **Conclude Clearly:** When your analysis determines the `next_action` is `final_answer`, provide a concise and accurate final answer to the user."""
+    )
+
+    FEW_SHOT_EXAMPLES = dedent(
+        """
+        Below are examples demonstrating how to use the `think` and `analyze` tools.
+
+        ### Examples
+
+        **Example 1: Simple Fact Retrieval**
+
+        *User Request:* How many continents are there on Earth?
+
+        *Agent's Internal Process:*
+
+        ```tool_call
+        think(
+          title="Understand Request",
+          thought="The user wants to know the standard number of continents on Earth. This is a common piece of knowledge.",
+          action="Recall or verify the number of continents.",
+          confidence=0.95
+        )
+        ```
+        *--(Agent internally recalls the fact)--*
+        ```tool_call
+        analyze(
+          title="Evaluate Fact",
+          result="Standard geographical models list 7 continents: Africa, Antarctica, Asia, Australia, Europe, North America, South America.",
+          analysis="The recalled information directly answers the user's question accurately.",
+          next_action="final_answer",
+          confidence=1.0
+        )
+        ```
+
+        *Agent's Final Answer to User:*
+        There are 7 continents on Earth: Africa, Antarctica, Asia, Australia, Europe, North America, and South America.
+
+        **Example 2: Multi-Step Information Gathering**
+
+        *User Request:* What is the capital of France and its current population?
+
+        *Agent's Internal Process:*
+
+        ```tool_call
+        think(
+          title="Plan Information Retrieval",
+          thought="The user needs two pieces of information: the capital of France and its current population. I should use external tools (like search) to find the most up-to-date and accurate information.",
+          action="First, search for the capital of France.",
+          confidence=0.95
+        )
+        ```
+
+        *Perform multiple tool calls in parallel*
+        *--(Tool call 1: search(query="capital of France"))--*
+        *--(Tool call 2: search(query="population of Paris current"))--*
+        *--(Tool Result 1: "Paris")--*
+        *--(Tool Result 2: "Approximately 2.1 million (city proper, estimate for early 2024)")--*
+
+        ```tool_call
+        analyze(
+          title="Analyze Capital Search Result",
+          result="The search result indicates Paris is the capital of France.",
+          analysis="This provides the first piece of requested information. Now I need to find the population of Paris.",
+          next_action="continue",
+          confidence=1.0
+        )
+        ```
+        ```tool_call
+        analyze(
+          title="Analyze Population Search Result",
+          result="The search provided an estimated population figure for Paris.",
+          analysis="I now have both the capital and its estimated population. I can provide the final answer.",
+          next_action="final_answer",
+          confidence=0.9
+        )
+        ```
+
+        *Agent's Final Answer to User:*
+        The capital of France is Paris. Its estimated population (city proper) is approximately 2.1 million as of early 2024."""
+    )