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

agno/utils/media.py

@@ -1,52 +1,373 @@
+import base64
+import time
+from enum import Enum
 from pathlib import Path
+from typing import List, Optional
 
-import requests
+import httpx
 
+from agno.media import Audio, File, Image, Video
+from agno.utils.log import log_info, log_warning
 
-def download_image(url, save_path):
+
+class SampleDataFileExtension(str, Enum):
+    DOCX = "docx"
+    PDF = "pdf"
+    TXT = "txt"
+    JSON = "json"
+    CSV = "csv"
+
+
+def download_image(url: str, output_path: str) -> bool:
     """
     Downloads an image from the specified URL and saves it to the given local path.
     Parameters:
     - url (str): URL of the image to download.
-    - save_path (str): Local filesystem path to save the image.
+    - output_path (str): Local filesystem path to save the image
     """
     try:
         # Send HTTP GET request to the image URL
-        response = requests.get(url, stream=True)
+        response = httpx.get(url)
         response.raise_for_status()  # Raise an exception for HTTP errors
 
         # Check if the response contains image content
         content_type = response.headers.get("Content-Type")
         if not content_type or not content_type.startswith("image"):
-            print(f"URL does not point to an image. Content-Type: {content_type}")
+            log_warning(f"URL does not point to an image. Content-Type: {content_type}")
             return False
 
-        path = Path(save_path)
+        path = Path(output_path)
         path.parent.mkdir(parents=True, exist_ok=True)
 
         # Write the image to the local file in binary mode
-        with open(save_path, "wb") as file:
-            for chunk in response.iter_content(chunk_size=8192):
+        with open(output_path, "wb") as file:
+            for chunk in response.iter_bytes(chunk_size=8192):
                 if chunk:
                     file.write(chunk)
 
-        print(f"Image successfully downloaded and saved to '{save_path}'.")
+        log_info(f"Image successfully downloaded and saved to '{output_path}'.")
         return True
 
-    except requests.exceptions.RequestException as e:
-        print(f"Error downloading the image: {e}")
+    except httpx.HTTPError as e:
+        log_warning(f"Error downloading the image: {e}")
         return False
     except IOError as e:
-        print(f"Error saving the image to '{save_path}': {e}")
+        log_warning(f"Error saving the image to '{output_path}': {e}")
         return False
 
 
+def download_audio(url: str, output_path: str) -> str:
+    """Download audio from URL"""
+    response = httpx.get(url)
+    response.raise_for_status()
+
+    with open(output_path, "wb") as f:
+        for chunk in response.iter_bytes(chunk_size=8192):
+            f.write(chunk)
+    return output_path
+
+
 def download_video(url: str, output_path: str) -> str:
     """Download video from URL"""
-    response = requests.get(url, stream=True)
+    response = httpx.get(url)
     response.raise_for_status()
 
     with open(output_path, "wb") as f:
-        for chunk in response.iter_content(chunk_size=8192):
+        for chunk in response.iter_bytes(chunk_size=8192):
             f.write(chunk)
     return output_path
+
+
+def download_file(url: str, output_path: str) -> None:
+    """
+    Download a file from a given URL and save it to the specified path.
+
+    Args:
+        url (str): The URL of the file to download
+        output_path (str): The local path where the file should be saved
+
+    Raises:
+        httpx.HTTPError: If the download fails
+    """
+    try:
+        response = httpx.get(url)
+        response.raise_for_status()
+
+        output_file = Path(output_path)
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(output_file, "wb") as f:
+            for chunk in response.iter_bytes(chunk_size=8192):
+                if chunk:
+                    f.write(chunk)
+
+    except httpx.HTTPError as e:
+        raise Exception(f"Failed to download file from {url}: {str(e)}")
+
+
+def save_base64_data(base64_data: str, output_path: str) -> bool:
+    """
+    Saves base64 string to the specified path as bytes.
+    """
+    try:
+        # Decode the base64 string into bytes
+        decoded_data = base64.b64decode(base64_data)
+    except Exception as e:
+        raise Exception(f"An unexpected error occurred during base64 decoding: {e}")
+
+    try:
+        path = Path(output_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write the bytes to the local file in binary mode
+        with open(path, "wb") as file:
+            file.write(decoded_data)
+
+        log_info(f"Data successfully saved to '{path}'.")
+        return True
+    except Exception as e:
+        raise Exception(f"An unexpected error occurred while saving data to '{output_path}': {e}")
+
+
+def wait_for_media_ready(url: str, timeout: int = 120, interval: int = 5, verbose: bool = True) -> bool:
+    """
+    Wait for media to be ready at URL by polling with HEAD requests.
+
+    Args:
+        url (str): The URL to check for media availability
+        timeout (int): Maximum time to wait in seconds (default: 120)
+        interval (int): Seconds between each check (default: 5)
+        verbose (bool): Whether to print progress messages (default: True)
+
+    Returns:
+        bool: True if media is ready, False if timeout reached
+    """
+    max_attempts = timeout // interval
+
+    if verbose:
+        log_info("Media generated! Waiting for upload to complete...")
+
+    for attempt in range(max_attempts):
+        try:
+            response = httpx.head(url, timeout=10)
+            response.raise_for_status()
+            if verbose:
+                log_info(f"Media ready: {url}")
+            return True
+        except httpx.HTTPError:
+            pass
+
+        if verbose and (attempt + 1) % 3 == 0:
+            log_info(f"Still processing... ({(attempt + 1) * interval}s elapsed)")
+
+        time.sleep(interval)
+
+    if verbose:
+        log_warning(f"Timeout waiting for media. Try this URL later: {url}")
+    return False
+
+
+def download_knowledge_filters_sample_data(
+    num_files: int = 5, file_extension: SampleDataFileExtension = SampleDataFileExtension.DOCX
+) -> List[str]:
+    """
+    Download sample data files with configurable file extension.
+
+    Args:
+        num_files (int): Number of files to download
+        file_extension (SampleDataFileExtension): File extension type (DOCX, PDF, TXT, JSON)
+
+    Returns:
+        List[str]: List of paths to downloaded files
+    """
+    file_paths = []
+    root_path = Path.cwd()
+
+    for i in range(1, num_files + 1):
+        if file_extension == SampleDataFileExtension.CSV:
+            filename = f"filters_{i}.csv"
+        else:
+            filename = f"cv_{i}.{file_extension.value}"
+
+        download_path = root_path / "cookbook" / "data" / filename
+        download_path.parent.mkdir(parents=True, exist_ok=True)
+
+        download_file(
+            f"https://agno-public.s3.us-east-1.amazonaws.com/demo_data/filters/{filename}", str(download_path)
+        )
+        file_paths.append(str(download_path))
+    return file_paths
+
+
+def reconstruct_image_from_dict(img_data):
+    """
+    Reconstruct an Image object from dictionary data.
+
+    Handles both base64-encoded content (from database) and regular image data (url/filepath).
+    """
+    try:
+        if isinstance(img_data, dict):
+            # If content is base64 string, decode it back to bytes
+            if "content" in img_data and isinstance(img_data["content"], str):
+                return Image.from_base64(
+                    img_data["content"],
+                    id=img_data.get("id"),
+                    mime_type=img_data.get("mime_type"),
+                    format=img_data.get("format"),
+                    detail=img_data.get("detail"),
+                    original_prompt=img_data.get("original_prompt"),
+                    revised_prompt=img_data.get("revised_prompt"),
+                    alt_text=img_data.get("alt_text"),
+                )
+            else:
+                # Regular image (filepath/url)
+                return Image(**img_data)
+        return img_data
+    except Exception as e:
+        log_warning(f"Failed to reconstruct image from dict: {e}")
+        return None
+
+
+def reconstruct_video_from_dict(vid_data):
+    """
+    Reconstruct a Video object from dictionary data.
+
+    Handles both base64-encoded content (from database) and regular video data (url/filepath).
+    """
+    try:
+        if isinstance(vid_data, dict):
+            # If content is base64 string, decode it back to bytes
+            if "content" in vid_data and isinstance(vid_data["content"], str):
+                return Video.from_base64(
+                    vid_data["content"],
+                    id=vid_data.get("id"),
+                    mime_type=vid_data.get("mime_type"),
+                    format=vid_data.get("format"),
+                )
+            else:
+                # Regular video (filepath/url)
+                return Video(**vid_data)
+        return vid_data
+    except Exception as e:
+        log_warning(f"Failed to reconstruct video from dict: {e}")
+        return None
+
+
+def reconstruct_audio_from_dict(aud_data):
+    """
+    Reconstruct an Audio object from dictionary data.
+
+    Handles both base64-encoded content (from database) and regular audio data (url/filepath).
+    """
+    try:
+        if isinstance(aud_data, dict):
+            # If content is base64 string, decode it back to bytes
+            if "content" in aud_data and isinstance(aud_data["content"], str):
+                return Audio.from_base64(
+                    aud_data["content"],
+                    id=aud_data.get("id"),
+                    mime_type=aud_data.get("mime_type"),
+                    transcript=aud_data.get("transcript"),
+                    expires_at=aud_data.get("expires_at"),
+                    sample_rate=aud_data.get("sample_rate", 24000),
+                    channels=aud_data.get("channels", 1),
+                )
+            else:
+                # Regular audio (filepath/url)
+                return Audio(**aud_data)
+        return aud_data
+    except Exception as e:
+        log_warning(f"Failed to reconstruct audio from dict: {e}")
+        return None
+
+
+def reconstruct_file_from_dict(file_data):
+    """
+    Reconstruct a File object from dictionary data.
+
+    Handles both base64-encoded content (from database) and regular file data (url/filepath).
+    """
+    try:
+        if isinstance(file_data, dict):
+            # If content is base64 string, decode it back to bytes
+            if "content" in file_data and isinstance(file_data["content"], str):
+                file_obj = File.from_base64(
+                    file_data["content"],
+                    id=file_data.get("id"),
+                    mime_type=file_data.get("mime_type"),
+                    filename=file_data.get("filename"),
+                    name=file_data.get("name"),
+                    format=file_data.get("format"),
+                )
+                # Preserve additional fields that from_base64 doesn't handle
+                if file_data.get("size") is not None:
+                    file_obj.size = file_data.get("size")
+                if file_data.get("file_type") is not None:
+                    file_obj.file_type = file_data.get("file_type")
+                if file_data.get("filepath") is not None:
+                    file_obj.filepath = file_data.get("filepath")
+                if file_data.get("url") is not None:
+                    file_obj.url = file_data.get("url")
+                return file_obj
+            else:
+                # Regular file (filepath/url)
+                return File(**file_data)
+        return file_data
+    except Exception as e:
+        log_warning(f"Failed to reconstruct file from dict: {e}")
+        return None
+
+
+def reconstruct_images(images: Optional[List[dict]]) -> Optional[List[Image]]:
+    """Reconstruct a list of Image objects from list of dictionaries.
+
+    Failed reconstructions are skipped with a warning logged.
+    """
+    if not images:
+        return None
+    reconstructed = [reconstruct_image_from_dict(img_data) for img_data in images]
+    valid_images = [img for img in reconstructed if img is not None]
+    return valid_images if valid_images else None
+
+
+def reconstruct_videos(videos: Optional[List[dict]]) -> Optional[List[Video]]:
+    """Reconstruct a list of Video objects from list of dictionaries.
+
+    Failed reconstructions are skipped with a warning logged.
+    """
+    if not videos:
+        return None
+    reconstructed = [reconstruct_video_from_dict(vid_data) for vid_data in videos]
+    valid_videos = [vid for vid in reconstructed if vid is not None]
+    return valid_videos if valid_videos else None
+
+
+def reconstruct_audio_list(audio: Optional[List[dict]]) -> Optional[List[Audio]]:
+    """Reconstruct a list of Audio objects from list of dictionaries.
+
+    Failed reconstructions are skipped with a warning logged.
+    """
+    if not audio:
+        return None
+    reconstructed = [reconstruct_audio_from_dict(aud_data) for aud_data in audio]
+    valid_audio = [aud for aud in reconstructed if aud is not None]
+    return valid_audio if valid_audio else None
+
+
+def reconstruct_files(files: Optional[List[dict]]) -> Optional[List[File]]:
+    """Reconstruct a list of File objects from list of dictionaries.
+
+    Failed reconstructions are skipped with a warning logged.
+    """
+    if not files:
+        return None
+    reconstructed = [reconstruct_file_from_dict(file_data) for file_data in files]
+    valid_files = [f for f in reconstructed if f is not None]
+    return valid_files if valid_files else None
+
+
+def reconstruct_response_audio(audio: Optional[dict]) -> Optional[Audio]:
+    """Reconstruct a single Audio object for response audio."""
+    if not audio:
+        return None
+    return reconstruct_audio_from_dict(audio)

agno/utils/merge_dict.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict
+from typing import Any, Dict, List
 
 
 def merge_dictionaries(a: Dict[str, Any], b: Dict[str, Any]) -> None:
@@ -18,3 +18,24 @@ def merge_dictionaries(a: Dict[str, Any], b: Dict[str, Any]) -> None:
             merge_dictionaries(a[key], b[key])
         else:
             a[key] = b[key]
+
+
+def merge_parallel_session_states(original_state: Dict[str, Any], modified_states: List[Dict[str, Any]]) -> None:
+    """
+    Smart merge for parallel session states that only applies actual changes.
+    This prevents parallel steps from overwriting each other's changes.
+    """
+    if not original_state or not modified_states:
+        return
+
+    # Collect all actual changes (keys where value differs from original)
+    all_changes = {}
+    for modified_state in modified_states:
+        if modified_state:
+            for key, value in modified_state.items():
+                if key not in original_state or original_state[key] != value:
+                    all_changes[key] = value
+
+    # Apply all collected changes to the original state
+    for key, value in all_changes.items():
+        original_state[key] = value

agno/utils/message.py

@@ -1,19 +1,92 @@
+from copy import deepcopy
 from typing import Dict, List, Union
 
+from pydantic import BaseModel
+
 from agno.models.message import Message
+from agno.utils.log import log_debug
+
+
+def filter_tool_calls(messages: List[Message], max_tool_calls: int) -> None:
+    """
+    Filter messages (in-place) to keep only the most recent N tool calls.
+
+    Args:
+        messages: List of messages to filter (modified in-place)
+        max_tool_calls: Number of recent tool calls to keep
+    """
+    # Count total tool calls
+    tool_call_count = sum(1 for m in messages if m.role == "tool")
+
+    # No filtering needed
+    if tool_call_count <= max_tool_calls:
+        return
+
+    # Collect tool_call_ids to keep (most recent N)
+    tool_call_ids_list: List[str] = []
+    for msg in reversed(messages):
+        if msg.role == "tool" and len(tool_call_ids_list) < max_tool_calls:
+            if msg.tool_call_id:
+                tool_call_ids_list.append(msg.tool_call_id)
 
+    tool_call_ids_to_keep: set[str] = set(tool_call_ids_list)
 
-def get_text_from_message(message: Union[List, Dict, str, Message]) -> str:
+    # Filter messages in-place
+    filtered_messages = []
+    for msg in messages:
+        if msg.role == "tool":
+            # Keep only tool results in our window
+            if msg.tool_call_id in tool_call_ids_to_keep:
+                filtered_messages.append(msg)
+        elif msg.role == "assistant" and msg.tool_calls:
+            # Filter tool_calls within the assistant message
+            # Use deepcopy to ensure complete isolation of the filtered message
+            filtered_msg = deepcopy(msg)
+            # Filter tool_calls
+            if filtered_msg.tool_calls is not None:
+                filtered_msg.tool_calls = [
+                    tc for tc in filtered_msg.tool_calls if tc.get("id") in tool_call_ids_to_keep
+                ]
+
+            if filtered_msg.tool_calls:
+                # Has tool_calls remaining, keep it
+                filtered_messages.append(filtered_msg)
+            # skip empty messages
+            elif filtered_msg.content:
+                filtered_msg.tool_calls = None
+                filtered_messages.append(filtered_msg)
+        else:
+            filtered_messages.append(msg)
+
+    messages[:] = filtered_messages
+
+    # Log filtering information
+    num_filtered = tool_call_count - len(tool_call_ids_to_keep)
+    log_debug(f"Filtered {num_filtered} tool calls, kept {len(tool_call_ids_to_keep)}")
+
+
+def get_text_from_message(message: Union[List, Dict, str, Message, BaseModel]) -> str:
     """Return the user texts from the message"""
+    import json
 
     if isinstance(message, str):
         return message
+    if isinstance(message, BaseModel):
+        return message.model_dump_json(indent=2, exclude_none=True)
     if isinstance(message, list):
         text_messages = []
         if len(message) == 0:
             return ""
 
-        if "type" in message[0]:
+        # Check if it's a list of Message objects
+        if isinstance(message[0], Message):
+            for m in message:
+                if isinstance(m, Message) and m.role == "user" and m.content is not None:
+                    # Recursively extract text from the message content
+                    content_text = get_text_from_message(m.content)
+                    if content_text:
+                        text_messages.append(content_text)
+        elif "type" in message[0]:
             for m in message:
                 m_type = m.get("type")
                 if m_type is not None and isinstance(m_type, str):
@@ -38,6 +111,8 @@ def get_text_from_message(message: Union[List, Dict, str, Message]) -> str:
     if isinstance(message, dict):
         if "content" in message:
             return get_text_from_message(message["content"])
+        else:
+            return json.dumps(message, indent=2)
     if isinstance(message, Message) and message.content is not None:
         return get_text_from_message(message.content)
     return ""

agno/utils/models/ai_foundry.py

@@ -0,0 +1,50 @@
+from typing import Any, Dict
+
+from agno.models.message import Message
+from agno.utils.log import log_warning
+from agno.utils.openai import images_to_message
+
+
+def format_message(message: Message, compress_tool_results: bool = False) -> Dict[str, Any]:
+    """
+    Format a message into the format expected by OpenAI.
+
+    Args:
+        message (Message): The message to format.
+        compress_tool_results: Whether to compress tool results.
+
+    Returns:
+        Dict[str, Any]: The formatted message.
+    """
+    # Use compressed content for tool messages if compression is active
+    content = message.content
+
+    if message.role == "tool":
+        content = message.get_content(use_compressed_content=compress_tool_results)
+
+    message_dict: Dict[str, Any] = {
+        "role": message.role,
+        "content": content,
+        "name": message.name,
+        "tool_call_id": message.tool_call_id,
+        "tool_calls": message.tool_calls,
+    }
+    message_dict = {k: v for k, v in message_dict.items() if v is not None}
+
+    if message.images is not None and len(message.images) > 0:
+        # Ignore non-string message content
+        # because we assume that the images/audio are already added to the message
+        if isinstance(message.content, str):
+            message_dict["content"] = [{"type": "text", "text": message.content}]
+            message_dict["content"].extend(images_to_message(images=message.images))
+
+    if message.audio is not None and len(message.audio) > 0:
+        log_warning("Audio input is currently unsupported.")
+
+    if message.files is not None and len(message.files) > 0:
+        log_warning("File input is currently unsupported.")
+
+    if message.videos is not None and len(message.videos) > 0:
+        log_warning("Video input is currently unsupported.")
+
+    return message_dict