agno 2.2.13__py3-none-any.whl

agno/utils/string.py

@@ -0,0 +1,231 @@
+import hashlib
+import json
+import re
+import uuid
+from typing import Optional, Type
+from uuid import uuid4
+
+from pydantic import BaseModel, ValidationError
+
+from agno.utils.log import logger
+
+
+def is_valid_uuid(uuid_str: str) -> bool:
+    """
+    Check if a string is a valid UUID
+
+    Args:
+        uuid_str: String to check
+
+    Returns:
+        bool: True if string is a valid UUID, False otherwise
+    """
+    from uuid import UUID
+
+    try:
+        UUID(str(uuid_str))
+        return True
+    except (ValueError, AttributeError, TypeError):
+        return False
+
+
+def url_safe_string(input_string):
+    # Replace spaces with dashes
+    safe_string = input_string.replace(" ", "-")
+
+    # Convert camelCase to kebab-case
+    safe_string = re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", safe_string).lower()
+
+    # Convert snake_case to kebab-case
+    safe_string = safe_string.replace("_", "-")
+
+    # Remove special characters, keeping alphanumeric, dashes, and dots
+    safe_string = re.sub(r"[^\w\-.]", "", safe_string)
+
+    # Ensure no consecutive dashes
+    safe_string = re.sub(r"-+", "-", safe_string)
+
+    return safe_string
+
+
+def hash_string_sha256(input_string):
+    # Encode the input string to bytes
+    encoded_string = input_string.encode("utf-8")
+
+    # Create a SHA-256 hash object
+    sha256_hash = hashlib.sha256()
+
+    # Update the hash object with the encoded string
+    sha256_hash.update(encoded_string)
+
+    # Get the hexadecimal digest of the hash
+    hex_digest = sha256_hash.hexdigest()
+
+    return hex_digest
+
+
+def _extract_json_objects(text: str) -> list[str]:
+    objs: list[str] = []
+    brace_depth = 0
+    start_idx: Optional[int] = None
+    for idx, ch in enumerate(text):
+        if ch == "{" and brace_depth == 0:
+            start_idx = idx
+        if ch == "{":
+            brace_depth += 1
+        elif ch == "}":
+            brace_depth -= 1
+            if brace_depth == 0 and start_idx is not None:
+                objs.append(text[start_idx : idx + 1])
+                start_idx = None
+    return objs
+
+
+def _clean_json_content(content: str) -> str:
+    """Clean and prepare JSON content for parsing."""
+    # Handle code blocks
+    if "```json" in content:
+        content = content.split("```json")[-1].strip()
+        parts = content.split("```")
+        parts.pop(-1)
+        content = "".join(parts)
+    elif "```" in content:
+        content = content.split("```")[1].strip()
+
+    # Replace markdown formatting like *"name"* or `"name"` with "name"
+    content = re.sub(r'[*`#]?"([A-Za-z0-9_]+)"[*`#]?', r'"\1"', content)
+
+    # Handle newlines and control characters
+    content = content.replace("\n", " ").replace("\r", "")
+    content = re.sub(r"[\x00-\x1F\x7F]", "", content)
+
+    # Escape quotes only in values, not keys
+    def escape_quotes_in_values(match):
+        key = match.group(1)
+        value = match.group(2)
+
+        if '\\"' in value:
+            unescaped_value = value.replace('\\"', '"')
+            escaped_value = unescaped_value.replace('"', '\\"')
+        else:
+            escaped_value = value.replace('"', '\\"')
+
+        return f'"{key}": "{escaped_value}'
+
+    # Find and escape quotes in field values
+    content = re.sub(r'"(?P<key>[^"]+)"\s*:\s*"(?P<value>.*?)(?="\s*(?:,|\}))', escape_quotes_in_values, content)
+
+    return content
+
+
+def _parse_individual_json(content: str, output_schema: Type[BaseModel]) -> Optional[BaseModel]:
+    """Parse individual JSON objects from content and merge them based on response model fields."""
+    candidate_jsons = _extract_json_objects(content)
+    merged_data: dict = {}
+
+    # Get the expected fields from the response model
+    model_fields = output_schema.model_fields if hasattr(output_schema, "model_fields") else {}
+
+    for candidate in candidate_jsons:
+        try:
+            candidate_obj = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+
+        if isinstance(candidate_obj, dict):
+            # Merge data based on model fields
+            for field_name, field_info in model_fields.items():
+                if field_name in candidate_obj:
+                    field_value = candidate_obj[field_name]
+                    # If field is a list, extend it; otherwise, use the latest value
+                    if isinstance(field_value, list):
+                        if field_name not in merged_data:
+                            merged_data[field_name] = []
+                        merged_data[field_name].extend(field_value)
+                    else:
+                        merged_data[field_name] = field_value
+
+    if not merged_data:
+        return None
+
+    try:
+        return output_schema.model_validate(merged_data)
+    except ValidationError as e:
+        logger.warning("Validation failed on merged data: %s", e)
+        return None
+
+
+def parse_response_model_str(content: str, output_schema: Type[BaseModel]) -> Optional[BaseModel]:
+    structured_output = None
+
+    # Extract thinking content first to prevent <think> tags from corrupting JSON
+    from agno.utils.reasoning import extract_thinking_content
+
+    # handle thinking content b/w <think> tags
+    if "</think>" in content:
+        reasoning_content, output_content = extract_thinking_content(content)
+        if reasoning_content:
+            content = output_content
+
+    # Clean content first to simplify all parsing attempts
+    cleaned_content = _clean_json_content(content)
+
+    try:
+        # First attempt: direct JSON validation on cleaned content
+        structured_output = output_schema.model_validate_json(cleaned_content)
+    except (ValidationError, json.JSONDecodeError):
+        try:
+            # Second attempt: Parse as Python dict
+            data = json.loads(cleaned_content)
+            structured_output = output_schema.model_validate(data)
+        except (ValidationError, json.JSONDecodeError) as e:
+            logger.warning(f"Failed to parse cleaned JSON: {e}")
+
+            # Third attempt: Extract individual JSON objects
+            candidate_jsons = _extract_json_objects(cleaned_content)
+
+            if len(candidate_jsons) == 1:
+                # Single JSON object - try to parse it directly
+                try:
+                    data = json.loads(candidate_jsons[0])
+                    structured_output = output_schema.model_validate(data)
+                except (ValidationError, json.JSONDecodeError):
+                    pass
+
+            if structured_output is None:
+                # Final attempt: Handle concatenated JSON objects with field merging
+                structured_output = _parse_individual_json(cleaned_content, output_schema)
+                if structured_output is None:
+                    logger.warning("All parsing attempts failed.")
+
+    return structured_output
+
+
+def generate_id(seed: Optional[str] = None) -> str:
+    """
+    Generate a deterministic UUID5 based on a seed string.
+    If no seed is provided, generate a random UUID4.
+
+    Args:
+        seed (str): The seed string to generate the UUID from.
+
+    Returns:
+        str: A deterministic UUID5 string.
+    """
+    if seed is None:
+        return str(uuid4())
+    return str(uuid.uuid5(uuid.NAMESPACE_DNS, seed))
+
+
+def generate_id_from_name(name: Optional[str] = None) -> str:
+    """
+    Generate a deterministic ID from a name string.
+    If no name is provided, generate a random UUID4.
+
+    Args:
+        name (str): The name string to generate the ID from.
+    """
+    if name:
+        return name.lower().replace(" ", "-").replace("_", "-")
+    else:
+        return str(uuid4())

agno/utils/team.py

@@ -0,0 +1,139 @@
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+
+from agno.agent import Agent
+from agno.media import Audio, File, Image, Video
+from agno.run.agent import RunOutput
+from agno.run.team import TeamRunOutput
+from agno.utils.log import log_debug
+from agno.utils.string import is_valid_uuid, url_safe_string
+
+if TYPE_CHECKING:
+    from agno.team.team import Team
+
+
+def format_member_agent_task(
+    task_description: str,
+    team_member_interactions_str: Optional[str] = None,
+    team_history_str: Optional[str] = None,
+) -> str:
+    member_task_str = ""
+
+    if team_member_interactions_str:
+        member_task_str += f"{team_member_interactions_str}\n\n"
+
+    if team_history_str:
+        member_task_str += f"{team_history_str}\n\n"
+
+    member_task_str += f"{task_description}"
+
+    return member_task_str
+
+
+def get_member_id(member: Union[Agent, "Team"]) -> str:
+    """
+    Get the ID of a member
+
+    If the member has an agent_id or team_id, use that if it is not a valid UUID.
+    Then if the member has a name, convert that to a URL safe string.
+    Then if the member has the default UUID ID, use that.
+    Otherwise, return None.
+    """
+    from agno.team.team import Team
+
+    if isinstance(member, Agent) and member.id is not None and (not is_valid_uuid(member.id)):
+        url_safe_member_id = url_safe_string(member.id)
+    elif isinstance(member, Team) and member.id is not None and (not is_valid_uuid(member.id)):
+        url_safe_member_id = url_safe_string(member.id)
+    elif member.name is not None:
+        url_safe_member_id = url_safe_string(member.name)
+    elif isinstance(member, Agent) and member.id is not None:
+        url_safe_member_id = member.id
+    elif isinstance(member, Team) and member.id is not None:
+        url_safe_member_id = member.id
+    else:
+        url_safe_member_id = None
+    return url_safe_member_id
+
+
+def add_interaction_to_team_run_context(
+    team_run_context: Dict[str, Any],
+    member_name: str,
+    task: str,
+    run_response: Union[RunOutput, TeamRunOutput],
+) -> None:
+    if "member_responses" not in team_run_context:
+        team_run_context["member_responses"] = []
+    team_run_context["member_responses"].append(
+        {
+            "member_name": member_name,
+            "task": task,
+            "run_response": run_response,
+        }
+    )
+    log_debug(f"Updated team run context with member name: {member_name}")
+
+
+def get_team_member_interactions_str(team_run_context: Dict[str, Any]) -> str:
+    if not team_run_context:
+        return ""
+    team_member_interactions_str = ""
+    if "member_responses" in team_run_context:
+        team_member_interactions_str += "<member_interaction_context>\nSee below interactions wit other team members.\n"
+
+        for interaction in team_run_context["member_responses"]:
+            response_dict = interaction["run_response"].to_dict()
+            response_content = (
+                response_dict.get("content")
+                or ",".join([tool.get("content", "") for tool in response_dict.get("tools", [])])
+                or ""
+            )
+            team_member_interactions_str += f"Member: {interaction['member_name']}\n"
+            team_member_interactions_str += f"Task: {interaction['task']}\n"
+            team_member_interactions_str += f"Response: {response_content}\n"
+            team_member_interactions_str += "\n"
+        team_member_interactions_str += "</member_interaction_context>\n"
+    return team_member_interactions_str
+
+
+def get_team_run_context_images(team_run_context: Dict[str, Any]) -> List[Image]:
+    if not team_run_context:
+        return []
+    images = []
+    if "member_responses" in team_run_context:
+        for interaction in team_run_context["member_responses"]:
+            if interaction["run_response"].images:
+                images.extend(interaction["run_response"].images)
+    return images
+
+
+def get_team_run_context_videos(team_run_context: Dict[str, Any]) -> List[Video]:
+    if not team_run_context:
+        return []
+    videos = []
+    if "member_responses" in team_run_context:
+        for interaction in team_run_context["member_responses"]:
+            if interaction["run_response"].videos:
+                videos.extend(interaction["run_response"].videos)
+    return videos
+
+
+def get_team_run_context_audio(team_run_context: Dict[str, Any]) -> List[Audio]:
+    if not team_run_context:
+        return []
+    audio = []
+    if "member_responses" in team_run_context:
+        for interaction in team_run_context["member_responses"]:
+            if interaction["run_response"].audio:
+                audio.extend(interaction["run_response"].audio)
+    return audio
+
+
+def get_team_run_context_files(team_run_context: Dict[str, Any]) -> List[File]:
+    if not team_run_context:
+        return []
+    files = []
+    if "member_responses" in team_run_context:
+        for interaction in team_run_context["member_responses"]:
+            if interaction["run_response"].files:
+                files.extend(interaction["run_response"].files)
+    return files

agno/utils/timer.py

@@ -0,0 +1,41 @@
+from time import perf_counter
+from typing import Optional
+
+
+class Timer:
+    """Timer class for timing code execution"""
+
+    def __init__(self):
+        self.start_time: Optional[float] = None
+        self.end_time: Optional[float] = None
+        self.elapsed_time: Optional[float] = None
+
+    @property
+    def elapsed(self) -> float:
+        return self.elapsed_time or (perf_counter() - self.start_time) if self.start_time else 0.0
+
+    def start(self) -> float:
+        self.start_time = perf_counter()
+        return self.start_time
+
+    def stop(self) -> float:
+        self.end_time = perf_counter()
+        if self.start_time is not None:
+            self.elapsed_time = self.end_time - self.start_time
+        return self.end_time
+
+    def __enter__(self) -> "Timer":
+        self.start_time = perf_counter()
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.end_time = perf_counter()
+        if self.start_time is not None:
+            self.elapsed_time = self.end_time - self.start_time
+
+    def to_dict(self):
+        return {
+            "start_time": str(self.start_time) if self.start_time is not None else None,
+            "end_time": str(self.end_time) if self.end_time is not None else None,
+            "elapsed": self.elapsed,
+        }

agno/utils/tools.py

@@ -0,0 +1,102 @@
+from typing import Any, Dict, Optional
+
+from agno.models.response import ToolExecution
+from agno.tools.function import Function, FunctionCall
+from agno.utils.functions import get_function_call
+
+
+def get_function_call_for_tool_call(
+    tool_call: Dict[str, Any], functions: Optional[Dict[str, Function]] = None
+) -> Optional[FunctionCall]:
+    if tool_call.get("type") == "function":
+        _tool_call_id = tool_call.get("id")
+        _tool_call_function = tool_call.get("function")
+        if _tool_call_function is not None:
+            _tool_call_function_name = _tool_call_function.get("name")
+            _tool_call_function_arguments_str = _tool_call_function.get("arguments") or "{}"
+            if _tool_call_function_name is not None:
+                return get_function_call(
+                    name=_tool_call_function_name,
+                    arguments=_tool_call_function_arguments_str,
+                    call_id=_tool_call_id,
+                    functions=functions,
+                )
+    return None
+
+
+def extract_tool_call_from_string(text: str, start_tag: str = "<tool_call>", end_tag: str = "</tool_call>"):
+    start_index = text.find(start_tag) + len(start_tag)
+    end_index = text.find(end_tag)
+
+    # Extracting the content between the tags
+    return text[start_index:end_index].strip()
+
+
+def remove_tool_calls_from_string(text: str, start_tag: str = "<tool_call>", end_tag: str = "</tool_call>"):
+    """Remove multiple tool calls from a string."""
+    while start_tag in text and end_tag in text:
+        start_index = text.find(start_tag)
+        end_index = text.find(end_tag) + len(end_tag)
+        text = text[:start_index] + text[end_index:]
+    return text
+
+
+def extract_tool_from_xml(xml_str):
+    # Find tool_name
+    tool_name_start = xml_str.find("<tool_name>") + len("<tool_name>")
+    tool_name_end = xml_str.find("</tool_name>")
+    tool_name = xml_str[tool_name_start:tool_name_end].strip()
+
+    # Find and process parameters block
+    params_start = xml_str.find("<parameters>") + len("<parameters>")
+    params_end = xml_str.find("</parameters>")
+    parameters_block = xml_str[params_start:params_end].strip()
+
+    # Extract individual parameters
+    arguments = {}
+    while parameters_block:
+        # Find the next tag and its closing
+        tag_start = parameters_block.find("<") + 1
+        tag_end = parameters_block.find(">")
+        tag_name = parameters_block[tag_start:tag_end]
+
+        # Find the tag's closing counterpart
+        value_start = tag_end + 1
+        value_end = parameters_block.find(f"</{tag_name}>")
+        value = parameters_block[value_start:value_end].strip()
+
+        # Add to arguments
+        arguments[tag_name] = value
+
+        # Move past this tag
+        parameters_block = parameters_block[value_end + len(f"</{tag_name}>") :].strip()
+
+    return {"tool_name": tool_name, "parameters": arguments}
+
+
+def remove_function_calls_from_string(
+    text: str, start_tag: str = "<function_calls>", end_tag: str = "</function_calls>"
+):
+    """Remove multiple function calls from a string."""
+    while start_tag in text and end_tag in text:
+        start_index = text.find(start_tag)
+        end_index = text.find(end_tag) + len(end_tag)
+        text = text[:start_index] + text[end_index:]
+    return text
+
+
+def get_function_call_for_tool_execution(
+    tool_execution: ToolExecution,
+    functions: Optional[Dict[str, Function]] = None,
+) -> Optional[FunctionCall]:
+    import json
+
+    _tool_call_id = tool_execution.tool_call_id
+    _tool_call_function_name = tool_execution.tool_name or ""
+    _tool_call_function_arguments_str = json.dumps(tool_execution.tool_args)
+    return get_function_call(
+        name=_tool_call_function_name,
+        arguments=_tool_call_function_arguments_str,
+        call_id=_tool_call_id,
+        functions=functions,
+    )

agno/utils/web.py

@@ -0,0 +1,23 @@
+import webbrowser
+from pathlib import Path
+
+from agno.utils.log import logger
+
+
+def open_html_file(file_path: Path):
+    """
+    Opens the specified HTML file in the default web browser.
+    :param file_path: Path to the HTML file.
+    """
+    # Resolve the absolute path
+    absolute_path = file_path.resolve()
+
+    if not absolute_path.is_file():
+        logger.error(f"The file '{absolute_path}' does not exist.")
+        raise FileNotFoundError(f"The file '{absolute_path}' does not exist.")
+
+    # Convert the file path to a file URI
+    file_url = absolute_path.as_uri()
+
+    # Open the file in the default web browser
+    webbrowser.open(file_url)