agno 2.2.13__py3-none-any.whl

agno/utils/prompts.py

@@ -0,0 +1,111 @@
+import json
+from typing import Type, Union
+
+from pydantic import BaseModel
+
+from agno.utils.log import log_warning
+
+
+def get_json_output_prompt(output_schema: Union[str, list, BaseModel]) -> str:
+    """Return the JSON output prompt for the Agent.
+
+    This is added to the system prompt when the output_schema is set and structured_outputs is False.
+    """
+
+    json_output_prompt = "Provide your output as a JSON containing the following fields:"
+    if output_schema is not None:
+        if isinstance(output_schema, str):
+            json_output_prompt += "\n<json_fields>"
+            json_output_prompt += f"\n{output_schema}"
+            json_output_prompt += "\n</json_fields>"
+        elif isinstance(output_schema, list):
+            json_output_prompt += "\n<json_fields>"
+            json_output_prompt += f"\n{json.dumps(output_schema)}"
+            json_output_prompt += "\n</json_fields>"
+        elif (
+            issubclass(type(output_schema), BaseModel)
+            or issubclass(output_schema, BaseModel)  # type: ignore
+            or isinstance(output_schema, BaseModel)
+        ):  # type: ignore
+            json_schema = output_schema.model_json_schema()
+            if json_schema is not None:
+                response_model_properties = {}
+                json_schema_properties = json_schema.get("properties")
+                if json_schema_properties is not None:
+                    for field_name, field_properties in json_schema_properties.items():
+                        formatted_field_properties = {
+                            prop_name: prop_value
+                            for prop_name, prop_value in field_properties.items()
+                            if prop_name != "title"
+                        }
+                        # Handle enum references
+                        if "allOf" in formatted_field_properties:
+                            ref = formatted_field_properties["allOf"][0].get("$ref", "")
+                            if ref.startswith("#/$defs/"):
+                                enum_name = ref.split("/")[-1]
+                                formatted_field_properties["enum_type"] = enum_name
+
+                        response_model_properties[field_name] = formatted_field_properties
+
+                json_schema_defs = json_schema.get("$defs")
+                if json_schema_defs is not None:
+                    response_model_properties["$defs"] = {}
+                    for def_name, def_properties in json_schema_defs.items():
+                        # Handle both regular object definitions and enums
+                        if "enum" in def_properties:
+                            # This is an enum definition
+                            response_model_properties["$defs"][def_name] = {
+                                "type": "string",
+                                "enum": def_properties["enum"],
+                                "description": def_properties.get("description", ""),
+                            }
+                        else:
+                            # This is a regular object definition
+                            def_fields = def_properties.get("properties")
+                            formatted_def_properties = {}
+                            if def_fields is not None:
+                                for field_name, field_properties in def_fields.items():
+                                    formatted_field_properties = {
+                                        prop_name: prop_value
+                                        for prop_name, prop_value in field_properties.items()
+                                        if prop_name != "title"
+                                    }
+                                    formatted_def_properties[field_name] = formatted_field_properties
+                            if len(formatted_def_properties) > 0:
+                                response_model_properties["$defs"][def_name] = formatted_def_properties
+
+                if len(response_model_properties) > 0:
+                    json_output_prompt += "\n<json_fields>"
+                    json_output_prompt += (
+                        f"\n{json.dumps([key for key in response_model_properties.keys() if key != '$defs'])}"
+                    )
+                    json_output_prompt += "\n</json_fields>"
+                    json_output_prompt += "\n\nHere are the properties for each field:"
+                    json_output_prompt += "\n<json_field_properties>"
+                    json_output_prompt += f"\n{json.dumps(response_model_properties, indent=2)}"
+                    json_output_prompt += "\n</json_field_properties>"
+        else:
+            log_warning(f"Could not build json schema for {output_schema}")
+    else:
+        json_output_prompt += "Provide the output as JSON."
+
+    json_output_prompt += "\nStart your response with `{` and end it with `}`."
+    json_output_prompt += "\nYour output will be passed to json.loads() to convert it to a Python object."
+    json_output_prompt += "\nMake sure it only contains valid JSON."
+    return json_output_prompt
+
+
+def get_response_model_format_prompt(output_schema: Type[BaseModel]) -> str:
+    """Return the format prompt for the response model."""
+
+    message = "Make sure your response is a valid string (NOT JSON) that mentions the following topics:"
+
+    # Extract field names and descriptions
+    for field_name, field_info in output_schema.model_fields.items():
+        description = field_info.description or ""
+        if description:
+            message += f"\n- {field_name}: {description}"
+        else:
+            message += f"\n- {field_name}"
+
+    return message

agno/utils/reasoning.py

@@ -0,0 +1,108 @@
+from typing import TYPE_CHECKING, List, Optional, Tuple, Union
+
+from agno.models.message import Message
+from agno.models.metrics import Metrics
+from agno.reasoning.step import ReasoningStep
+
+if TYPE_CHECKING:
+    from agno.run.agent import RunOutput
+    from agno.team.team import TeamRunOutput
+
+
+def extract_thinking_content(content: str) -> Tuple[Optional[str], str]:
+    """Extract thinking content from response text between <think> tags."""
+    if not content or "</think>" not in content:
+        return None, content
+
+    # Find the end of thinking content
+    end_idx = content.find("</think>")
+
+    # Look for opening <think> tag, if not found, assume thinking starts at beginning
+    start_idx = content.find("<think>")
+    if start_idx == -1:
+        reasoning_content = content[:end_idx].strip()
+    else:
+        start_idx = start_idx + len("<think>")
+        reasoning_content = content[start_idx:end_idx].strip()
+
+    output_content = content[end_idx + len("</think>") :].strip()
+
+    return reasoning_content, output_content
+
+
+def append_to_reasoning_content(run_response: Union["RunOutput", "TeamRunOutput"], content: str) -> None:
+    """Helper to append content to the reasoning_content field."""
+    if not hasattr(run_response, "reasoning_content") or not run_response.reasoning_content:  # type: ignore
+        run_response.reasoning_content = content  # type: ignore
+    else:
+        run_response.reasoning_content += content  # type: ignore
+
+
+def add_reasoning_step_to_metadata(
+    run_response: Union["RunOutput", "TeamRunOutput"], reasoning_step: ReasoningStep
+) -> None:
+    if run_response.reasoning_steps is None:
+        run_response.reasoning_steps = []
+
+    run_response.reasoning_steps.append(reasoning_step)
+
+
+def add_reasoning_metrics_to_metadata(
+    run_response: Union["RunOutput", "TeamRunOutput"], reasoning_time_taken: float
+) -> None:
+    try:
+        # Initialize reasoning_messages if it doesn't exist
+        if run_response.reasoning_messages is None:
+            run_response.reasoning_messages = []
+
+        metrics_message = Message(
+            role="assistant",
+            content=run_response.reasoning_content,
+            metrics=Metrics(duration=reasoning_time_taken),
+        )
+
+        # Add the metrics message to the reasoning_messages
+        run_response.reasoning_messages.append(metrics_message)
+
+    except Exception as e:
+        # Log the error but don't crash
+        from agno.utils.log import log_error
+
+        log_error(f"Failed to add reasoning metrics to metadata: {str(e)}")
+
+
+def update_run_output_with_reasoning(
+    run_response: Union["RunOutput", "TeamRunOutput"],
+    reasoning_steps: List[ReasoningStep],
+    reasoning_agent_messages: List[Message],
+) -> None:
+    # Update reasoning_steps
+    if run_response.reasoning_steps is None:
+        run_response.reasoning_steps = reasoning_steps
+    else:
+        run_response.reasoning_steps.extend(reasoning_steps)
+
+    # Update reasoning_messages
+    if run_response.reasoning_messages is None:
+        run_response.reasoning_messages = reasoning_agent_messages
+    else:
+        run_response.reasoning_messages.extend(reasoning_agent_messages)
+
+    # Create and store reasoning_content
+    reasoning_content = ""
+    for step in reasoning_steps:
+        if step.title:
+            reasoning_content += f"## {step.title}\n"
+        if step.reasoning:
+            reasoning_content += f"{step.reasoning}\n"
+        if step.action:
+            reasoning_content += f"Action: {step.action}\n"
+        if step.result:
+            reasoning_content += f"Result: {step.result}\n"
+        reasoning_content += "\n"
+
+    # Add to existing reasoning_content or set it
+    if not run_response.reasoning_content:
+        run_response.reasoning_content = reasoning_content
+    else:
+        run_response.reasoning_content += reasoning_content

agno/utils/response.py

@@ -0,0 +1,163 @@
+from typing import AsyncIterator, Iterator, List, Set, Union
+
+from agno.exceptions import RunCancelledException
+from agno.models.response import ToolExecution
+from agno.reasoning.step import ReasoningStep
+from agno.run.agent import RunOutput, RunOutputEvent, RunPausedEvent
+from agno.run.team import TeamRunOutput, TeamRunOutputEvent
+
+
+def create_panel(content, title, border_style="blue"):
+    from rich.box import HEAVY
+    from rich.panel import Panel
+
+    return Panel(
+        content, title=title, title_align="left", border_style=border_style, box=HEAVY, expand=True, padding=(1, 1)
+    )
+
+
+def build_reasoning_step_panel(
+    step_idx: int, step: ReasoningStep, show_full_reasoning: bool = False, color: str = "green"
+):
+    from rich.text import Text
+
+    # Build step content
+    step_content = Text.assemble()
+    if step.title is not None:
+        step_content.append(f"{step.title}\n", "bold")
+    if step.action is not None:
+        step_content.append(Text.from_markup(f"[bold]Action:[/bold] {step.action}\n", style="dim"))
+    if step.result is not None:
+        step_content.append(Text.from_markup(step.result, style="dim"))
+
+    if show_full_reasoning:
+        # Add detailed reasoning information if available
+        if step.reasoning is not None:
+            step_content.append(Text.from_markup(f"\n[bold]Reasoning:[/bold] {step.reasoning}", style="dim"))
+        if step.confidence is not None:
+            step_content.append(Text.from_markup(f"\n[bold]Confidence:[/bold] {step.confidence}", style="dim"))
+    return create_panel(content=step_content, title=f"Reasoning step {step_idx}", border_style=color)
+
+
+def escape_markdown_tags(content: str, tags: Set[str]) -> str:
+    """Escape special tags in markdown content."""
+    escaped_content = content
+    for tag in tags:
+        # Escape opening tag
+        escaped_content = escaped_content.replace(f"<{tag}>", f"&lt;{tag}&gt;")
+        # Escape closing tag
+        escaped_content = escaped_content.replace(f"</{tag}>", f"&lt;/{tag}&gt;")
+    return escaped_content
+
+
+def check_if_run_cancelled(run_output: Union[RunOutput, RunOutputEvent, TeamRunOutput, TeamRunOutputEvent]):
+    if run_output.is_cancelled:
+        raise RunCancelledException()
+
+
+def format_tool_calls(tool_calls: List[ToolExecution]) -> List[str]:
+    """Format tool calls for display in a readable format.
+
+    Args:
+        tool_calls: List of tool call dictionaries containing tool_name and tool_args
+
+    Returns:
+        List[str]: List of formatted tool call strings
+    """
+    formatted_tool_calls = []
+
+    for tool_call in tool_calls:
+        if tool_call.tool_name is not None:
+            tool_name = tool_call.tool_name
+            args_str = ""
+            if tool_call.tool_args is not None and tool_call.tool_args:  # Check if args exist and are non-empty
+                args_str = ", ".join(f"{k}={v}" for k, v in tool_call.tool_args.items())
+            formatted_tool_calls.append(f"{tool_name}({args_str})")
+
+    return formatted_tool_calls
+
+
+def create_paused_run_output_panel(run_output: Union[RunPausedEvent, RunOutput]):
+    from rich.text import Text
+
+    tool_calls_content = Text("Run is paused. ")
+    if run_output.tools is not None:
+        if any(tc.requires_confirmation for tc in run_output.tools):
+            tool_calls_content.append("The following tool calls require confirmation:\n")
+        for tool_call in run_output.tools:
+            if tool_call.requires_confirmation:
+                args_str = ""
+                for arg, value in tool_call.tool_args.items() if tool_call.tool_args else {}:
+                    args_str += f"{arg}={value}, "
+                args_str = args_str.rstrip(", ")
+                tool_calls_content.append(f"• {tool_call.tool_name}({args_str})\n")
+        if any(tc.requires_user_input for tc in run_output.tools):
+            tool_calls_content.append("The following tool calls require user input:\n")
+        for tool_call in run_output.tools:
+            if tool_call.requires_user_input:
+                args_str = ""
+                for arg, value in tool_call.tool_args.items() if tool_call.tool_args else {}:
+                    args_str += f"{arg}={value}, "
+                args_str = args_str.rstrip(", ")
+                tool_calls_content.append(f"• {tool_call.tool_name}({args_str})\n")
+        if any(tc.external_execution_required for tc in run_output.tools):
+            tool_calls_content.append("The following tool calls require external execution:\n")
+        for tool_call in run_output.tools:
+            if tool_call.external_execution_required:
+                args_str = ""
+                for arg, value in tool_call.tool_args.items() if tool_call.tool_args else {}:
+                    args_str += f"{arg}={value}, "
+                args_str = args_str.rstrip(", ")
+                tool_calls_content.append(f"• {tool_call.tool_name}({args_str})\n")
+
+    # Create panel for response
+    response_panel = create_panel(
+        content=tool_calls_content,
+        title="Run Paused",
+        border_style="blue",
+    )
+    return response_panel
+
+
+def get_paused_content(run_output: RunOutput) -> str:
+    paused_content = ""
+    for tool in run_output.tools or []:
+        # Initialize flags for each tool
+        confirmation_required = False
+        user_input_required = False
+        external_execution_required = False
+
+        if tool.requires_confirmation is not None and tool.requires_confirmation is True and not tool.confirmed:
+            confirmation_required = True
+        if tool.requires_user_input is not None and tool.requires_user_input is True:
+            user_input_required = True
+        if tool.external_execution_required is not None and tool.external_execution_required is True:
+            external_execution_required = True
+
+        if confirmation_required and user_input_required and external_execution_required:
+            paused_content = "I have tools to execute, but I need confirmation, user input, or external execution."
+        elif confirmation_required and user_input_required:
+            paused_content = "I have tools to execute, but I need confirmation or user input."
+        elif confirmation_required and external_execution_required:
+            paused_content = "I have tools to execute, but I need confirmation or external execution."
+        elif user_input_required and external_execution_required:
+            paused_content = "I have tools to execute, but I need user input or external execution."
+        elif confirmation_required:
+            paused_content = "I have tools to execute, but I need confirmation."
+        elif user_input_required:
+            paused_content = "I have tools to execute, but I need user input."
+        elif external_execution_required:
+            paused_content = "I have tools to execute, but it needs external execution."
+    return paused_content
+
+
+def generator_wrapper(
+    event: Union[RunOutputEvent, TeamRunOutputEvent],
+) -> Iterator[Union[RunOutputEvent, TeamRunOutputEvent]]:
+    yield event
+
+
+async def async_generator_wrapper(
+    event: Union[RunOutputEvent, TeamRunOutputEvent],
+) -> AsyncIterator[Union[RunOutputEvent, TeamRunOutputEvent]]:
+    yield event

agno/utils/response_iterator.py

@@ -0,0 +1,17 @@
+class ResponseIterator:
+    def __init__(self):
+        self.items = []
+        self.index = 0
+
+    def add(self, item):
+        self.items.append(item)
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        if self.index >= len(self.items):
+            raise StopIteration
+        item = self.items[self.index]
+        self.index += 1
+        return item

agno/utils/safe_formatter.py

@@ -0,0 +1,24 @@
+import string
+
+
+class SafeFormatter(string.Formatter):
+    def get_value(self, key, args, kwargs):
+        """Handle missing keys by returning '{key}'."""
+        if key not in kwargs:
+            return f"{key}"
+        return kwargs[key]
+
+    def format_field(self, value, format_spec):
+        """
+        If Python sees something like 'somekey:"stuff"', it tries to parse
+        it as a format spec and might raise ValueError. We catch it here
+        and just return the literal placeholder.
+        """
+        if not format_spec:
+            return super().format_field(value, format_spec)
+
+        try:
+            return super().format_field(value, format_spec)
+        except ValueError:
+            # On invalid format specifiers, keep them literal
+            return f"{{{value}:{format_spec}}}"

agno/utils/serialize.py

@@ -0,0 +1,32 @@
+"""JSON serialization utilities for handling datetime and enum objects."""
+
+from datetime import date, datetime, time
+from enum import Enum
+from typing import Any
+
+
+def json_serializer(obj: Any) -> Any:
+    """Custom JSON serializer for objects not serializable by default json module.
+
+    Handles:
+    - datetime, date, time objects -> ISO format strings
+    - Enum objects -> their values (or names if values are not JSON-serializable)
+    - All other objects -> string representation
+
+    Args:
+        obj: Object to serialize
+
+    Returns:
+        JSON-serializable representation of the object
+    """
+    # Datetime like
+    if isinstance(obj, (datetime, date, time)):
+        return obj.isoformat()
+
+    # Enums
+    if isinstance(obj, Enum):
+        v = obj.value
+        return v if isinstance(v, (str, int, float, bool, type(None))) else obj.name
+
+    # Fallback to string
+    return str(obj)

agno/utils/shell.py

@@ -0,0 +1,22 @@
+from typing import List
+
+from agno.utils.log import log_debug, log_info, logger
+
+
+def run_shell_command(args: List[str], tail: int = 100) -> str:
+    log_info(f"Running shell command: {args}")
+
+    import subprocess
+
+    try:
+        result = subprocess.run(args, capture_output=True, text=True)
+        log_debug(f"Result: {result}")
+        log_debug(f"Return code: {result.returncode}")
+        if result.returncode != 0:
+            return f"Error: {result.stderr}"
+
+        # return only the last n lines of the output
+        return "\n".join(result.stdout.split("\n")[-tail:])
+    except Exception as e:
+        logger.warning(f"Failed to run shell command: {e}")
+        return f"Error: {e}"