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

agno/utils/models/openai_responses.py

@@ -0,0 +1,140 @@
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from agno.media import Image
+from agno.utils.log import logger
+
+
+def _process_bytes_image(image: bytes) -> Dict[str, Any]:
+    """Process bytes image data."""
+    import base64
+
+    base64_image = base64.b64encode(image).decode("utf-8")
+    image_url = f"data:image/jpeg;base64,{base64_image}"
+    return {"type": "input_image", "image_url": image_url}
+
+
+def _process_image_path(image_path: Union[Path, str]) -> Dict[str, Any]:
+    """Process image ( file path)."""
+    # Process local file image
+    import base64
+    import mimetypes
+
+    path = image_path if isinstance(image_path, Path) else Path(image_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Image file not found: {image_path}")
+
+    mime_type = mimetypes.guess_type(image_path)[0] or "image/jpeg"
+    with open(path, "rb") as image_file:
+        base64_image = base64.b64encode(image_file.read()).decode("utf-8")
+        image_url = f"data:{mime_type};base64,{base64_image}"
+        return {"type": "input_image", "image_url": image_url}
+
+
+def _process_image_url(image_url: str) -> Dict[str, Any]:
+    """Process image (base64 or URL)."""
+
+    if image_url.startswith("data:image") or image_url.startswith(("http://", "https://")):
+        return {"type": "input_image", "image_url": image_url}
+    else:
+        raise ValueError("Image URL must start with 'data:image' or 'http(s)://'.")
+
+
+def _process_image(image: Image) -> Optional[Dict[str, Any]]:
+    """Process an image based on the format."""
+
+    if image.url is not None:
+        image_payload = _process_image_url(image.url)
+
+    elif image.filepath is not None:
+        image_payload = _process_image_path(image.filepath)
+
+    elif image.content is not None:
+        image_payload = _process_bytes_image(image.content)
+
+    else:
+        logger.warning(f"Unsupported image format: {image}")
+        return None
+
+    if image.detail:
+        image_payload["image_url"]["detail"] = image.detail
+
+    return image_payload
+
+
+def images_to_message(images: Sequence[Image]) -> List[Dict[str, Any]]:
+    """
+    Add images to a message for the model. By default, we use the OpenAI image format but other Models
+    can override this method to use a different image format.
+
+    Args:
+        images: Sequence of images in various formats:
+            - str: base64 encoded image, URL, or file path
+            - Dict: pre-formatted image data
+            - bytes: raw image data
+
+    Returns:
+        Message content with images added in the format expected by the model
+    """
+
+    # Create a default message content with text
+    image_messages: List[Dict[str, Any]] = []
+
+    # Add images to the message content
+    for image in images:
+        try:
+            image_data = _process_image(image)
+            if image_data:
+                image_messages.append(image_data)
+        except Exception as e:
+            logger.error(f"Failed to process image: {str(e)}")
+            continue
+
+    return image_messages
+
+
+def sanitize_response_schema(schema: dict):
+    """
+    Recursively sanitize a Pydantic-generated JSON schema to comply with OpenAI's response_format rules:
+
+    - Sets "additionalProperties": false for all object types to disallow extra fields,
+      EXCEPT when additionalProperties is already defined with a schema (Dict types).
+    - Removes "default": null from optional fields.
+    - Ensures that all fields defined in "properties" are listed in "required",
+      making every property explicitly required as per OpenAI's expectations,
+      EXCEPT for Dict fields which should not be in the required array.
+    """
+    if isinstance(schema, dict):
+        # Enforce additionalProperties: false for object types, but preserve Dict schemas
+        if schema.get("type") == "object":
+            # Only set additionalProperties to False if it's not already defined with a schema
+            # This preserves Dict[str, T] fields which need additionalProperties to define value types
+            if "additionalProperties" not in schema:
+                schema["additionalProperties"] = False
+            elif schema.get("additionalProperties") is True:
+                # Convert True to False for strict mode, but preserve schema objects
+                schema["additionalProperties"] = False
+
+            # Ensure all properties are required, EXCEPT Dict fields
+            if "properties" in schema:
+                from agno.utils.models.schema_utils import is_dict_field
+
+                required_fields = []
+                for prop_name, prop_schema in schema["properties"].items():
+                    # Use the utility function to check if this is a Dict field
+                    if not is_dict_field(prop_schema):
+                        required_fields.append(prop_name)
+
+                schema["required"] = required_fields
+
+        # Remove only default: null
+        if "default" in schema and schema["default"] is None:
+            schema.pop("default")
+
+        # Recurse into all values
+        for value in schema.values():
+            sanitize_response_schema(value)
+
+    elif isinstance(schema, list):
+        for item in schema:
+            sanitize_response_schema(item)

agno/utils/models/schema_utils.py

@@ -0,0 +1,153 @@
+"""
+Utility functions for handling JSON schemas across different model providers.
+This module provides model-agnostic schema transformations and validations.
+"""
+
+from typing import Any, Dict, Type
+
+from pydantic import BaseModel
+
+
+def is_dict_field(schema: Dict[str, Any]) -> bool:
+    """
+    Check if a schema represents a Dict[str, T] field.
+
+    Args:
+        schema: JSON schema dictionary
+
+    Returns:
+        bool: True if the schema represents a Dict field
+    """
+    return (
+        schema.get("type") == "object"
+        and "additionalProperties" in schema
+        and isinstance(schema["additionalProperties"], dict)
+        and "type" in schema["additionalProperties"]
+        and "properties" not in schema
+    )
+
+
+def get_dict_value_type(schema: Dict[str, Any]) -> str:
+    """
+    Extract the value type from a Dict field schema.
+
+    Args:
+        schema: JSON schema dictionary for a Dict field
+
+    Returns:
+        str: The type of values in the dictionary (e.g., "integer", "string")
+    """
+    if is_dict_field(schema):
+        return schema["additionalProperties"]["type"]
+    return "string"
+
+
+def normalize_schema_for_provider(schema: Dict[str, Any], provider: str) -> Dict[str, Any]:
+    """
+    Normalize a Pydantic-generated schema for a specific model provider.
+
+    Args:
+        schema: Original Pydantic JSON schema
+        provider: Model provider name ("openai", "gemini", "anthropic", etc.)
+
+    Returns:
+        Dict[str, Any]: Normalized schema for the provider
+    """
+    # Make a deep copy to avoid modifying the original
+    import copy
+
+    normalized = copy.deepcopy(schema)
+
+    if provider.lower() == "openai":
+        return _normalize_for_openai(normalized)
+    elif provider.lower() == "gemini":
+        return _normalize_for_gemini(normalized)
+    else:
+        # Default normalization for other providers
+        return _normalize_generic(normalized)
+
+
+def _normalize_for_openai(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Normalize schema for OpenAI structured outputs."""
+    from agno.utils.models.openai_responses import sanitize_response_schema
+
+    sanitize_response_schema(schema)
+    return schema
+
+
+def _normalize_for_gemini(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Normalize schema for Gemini.
+    Gemini has specific requirements for object types and doesn't support
+    additionalProperties in the same way as JSON Schema.
+    """
+
+    def _process_schema(s: Dict[str, Any]) -> None:
+        if isinstance(s, dict):
+            # Handle Dict fields - preserve additionalProperties info for convert_schema
+            if is_dict_field(s):
+                # For Gemini, we need to preserve the additionalProperties info
+                # so that convert_schema can create appropriate placeholder properties
+                value_type = get_dict_value_type(s)
+
+                # Update description to indicate this is a dictionary
+                current_desc = s.get("description", "")
+                if current_desc:
+                    s["description"] = f"{current_desc} (Dictionary with {value_type} values)"
+                else:
+                    s["description"] = f"Dictionary with {value_type} values"
+
+                # Keep additionalProperties for convert_schema to process
+                # Don't remove it here - let convert_schema handle the conversion
+
+            # Recursively process nested schemas
+            for value in s.values():
+                if isinstance(value, dict):
+                    _process_schema(value)
+                elif isinstance(value, list):
+                    for item in value:
+                        if isinstance(item, dict):
+                            _process_schema(item)
+
+    _process_schema(schema)
+    return schema
+
+
+def _normalize_generic(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Generic normalization for other providers."""
+
+    def _process_schema(s: Dict[str, Any]) -> None:
+        if isinstance(s, dict):
+            # Remove null defaults
+            if "default" in s and s["default"] is None:
+                s.pop("default")
+
+            # Recursively process nested schemas
+            for value in s.values():
+                if isinstance(value, dict):
+                    _process_schema(value)
+                elif isinstance(value, list):
+                    for item in value:
+                        if isinstance(item, dict):
+                            _process_schema(item)
+
+    _process_schema(schema)
+    return schema
+
+
+def get_response_schema_for_provider(output_schema: Type[BaseModel], provider: str) -> Dict[str, Any]:
+    """
+    Get a properly formatted response schema for a specific model provider.
+
+    Args:
+        output_schema: Pydantic BaseModel class
+        provider: Model provider name
+
+    Returns:
+        Dict[str, Any]: Provider-specific schema
+    """
+    # Generate the base schema
+    base_schema = output_schema.model_json_schema()
+
+    # Normalize for the specific provider
+    return normalize_schema_for_provider(base_schema, provider)

agno/utils/models/watsonx.py

@@ -0,0 +1,41 @@
+from typing import Any, Dict, List, Sequence
+
+from agno.media import Image
+from agno.models.message import Message
+from agno.utils.log import log_error, log_warning
+
+
+def format_images_for_message(message: Message, images: Sequence[Image]) -> Message:
+    """
+    Format an image into the format expected by WatsonX.
+    """
+
+    # Create a default message content with text
+    message_content_with_image: List[Dict[str, Any]] = [{"type": "text", "text": message.content}]
+
+    # Add images to the message content
+    for image in images:
+        try:
+            if image.content is not None:
+                image_content = image.content
+            elif image.url is not None:
+                image_content = image.get_content_bytes()  # type: ignore
+            else:
+                log_warning(f"Unsupported image format: {image}")
+                continue
+
+            if image_content is not None:
+                import base64
+
+                base64_image = base64.b64encode(image_content).decode("utf-8")
+                image_url = f"data:image/jpeg;base64,{base64_image}"
+                image_payload = {"type": "image_url", "image_url": {"url": image_url}}
+                message_content_with_image.append(image_payload)
+
+        except Exception as e:
+            log_error(f"Failed to process image: {str(e)}")
+
+    # Update the message content with the images
+    if len(message_content_with_image) > 1:
+        message.content = message_content_with_image
+    return message

agno/utils/openai.py

@@ -0,0 +1,257 @@
+import base64
+import mimetypes
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from agno.media import Audio, File, Image
+from agno.utils.log import log_error, log_warning
+
+# Ensure .webp is recognized
+mimetypes.add_type("image/webp", ".webp")
+
+
+def audio_to_message(audio: Sequence[Audio]) -> List[Dict[str, Any]]:
+    """
+    Add audio to a message for the model. By default, we use the OpenAI audio format but other Models
+    can override this method to use a different audio format.
+
+    Args:
+        audio: Pre-formatted audio data like {
+                    "content": encoded_string,
+                    "format": "wav"
+                }
+
+    Returns:
+        Message content with audio added in the format expected by the model
+    """
+    from urllib.parse import urlparse
+
+    audio_messages = []
+    for audio_snippet in audio:
+        encoded_string: Optional[str] = None
+        audio_format: Optional[str] = audio_snippet.format
+
+        # The audio is raw data
+        if audio_snippet.content:
+            encoded_string = base64.b64encode(audio_snippet.content).decode("utf-8")
+            if not audio_format:
+                audio_format = "wav"  # Default format if not provided
+
+        # The audio is a URL
+        elif audio_snippet.url:
+            audio_bytes = audio_snippet.get_content_bytes()
+            if audio_bytes is not None:
+                encoded_string = base64.b64encode(audio_bytes).decode("utf-8")
+                if not audio_format:
+                    # Try to guess format from URL extension
+                    try:
+                        # Parse the URL first to isolate the path
+                        parsed_url = urlparse(audio_snippet.url)
+                        # Get suffix from the path component only
+                        audio_format = Path(parsed_url.path).suffix.lstrip(".")
+                        if not audio_format:  # Handle cases like URLs ending in /
+                            log_warning(
+                                f"Could not determine audio format from URL path: {parsed_url.path}. Defaulting."
+                            )
+                            audio_format = "wav"
+                    except Exception as e:
+                        log_warning(
+                            f"Could not determine audio format from URL: {audio_snippet.url}. Error: {e}. Defaulting."
+                        )
+                        audio_format = "wav"  # Default if guessing fails
+
+        # The audio is a file path
+        elif audio_snippet.filepath:
+            path = Path(audio_snippet.filepath)
+            if path.exists() and path.is_file():
+                try:
+                    with open(path, "rb") as audio_file:
+                        encoded_string = base64.b64encode(audio_file.read()).decode("utf-8")
+                    if not audio_format:
+                        audio_format = path.suffix.lstrip(".")
+                except Exception as e:
+                    log_error(f"Failed to read audio file {path}: {e}")
+                    continue  # Skip this audio snippet if file reading fails
+            else:
+                log_error(f"Audio file not found or is not a file: {path}")
+                continue  # Skip if file doesn't exist
+
+        # Append the message if we successfully processed the audio
+        if encoded_string and audio_format:
+            audio_messages.append(
+                {
+                    "type": "input_audio",
+                    "input_audio": {
+                        "data": encoded_string,
+                        "format": audio_format,
+                    },
+                },
+            )
+        else:
+            log_error(f"Could not process audio snippet: {audio_snippet}")
+
+    return audio_messages
+
+
+def _process_bytes_image(image: bytes, image_format: Optional[str] = None) -> Dict[str, Any]:
+    """Process bytes image data."""
+    base64_image = base64.b64encode(image).decode("utf-8")
+
+    # Use provided format or attempt detection, defaulting to JPEG
+    if image_format:
+        mime_type = f"image/{image_format.lower()}"
+    else:
+        # Try to detect the image format from the bytes
+        try:
+            import imghdr
+
+            detected_format = imghdr.what(None, h=image)
+            mime_type = f"image/{detected_format}" if detected_format else "image/jpeg"
+        except Exception:
+            mime_type = "image/jpeg"
+
+    image_url = f"data:{mime_type};base64,{base64_image}"
+    return {"type": "image_url", "image_url": {"url": image_url}}
+
+
+def _process_image_path(image_path: Union[Path, str]) -> Dict[str, Any]:
+    """Process image ( file path)."""
+    # Process local file image
+    path = Path(image_path)  # Ensure it's a Path object
+    if not path.exists():
+        raise FileNotFoundError(f"Image file not found: {image_path}")
+    if not path.is_file():
+        raise IsADirectoryError(f"Image path is not a file: {image_path}")
+
+    mime_type = mimetypes.guess_type(path)[0] or "image/jpeg"  # Default to jpeg if guess fails
+    try:
+        with open(path, "rb") as image_file:
+            base64_image = base64.b64encode(image_file.read()).decode("utf-8")
+            image_url = f"data:{mime_type};base64,{base64_image}"
+            return {"type": "image_url", "image_url": {"url": image_url}}
+    except Exception as e:
+        log_error(f"Failed to read image file {path}: {e}")
+        raise  # Re-raise the exception after logging
+
+
+def _process_image_url(image_url: str) -> Dict[str, Any]:
+    """Process image (base64 or URL)."""
+
+    if image_url.startswith("data:image") or image_url.startswith(("http://", "https://")):
+        return {"type": "image_url", "image_url": {"url": image_url}}
+    else:
+        raise ValueError("Image URL must start with 'data:image' or 'http(s)://'.")
+
+
+def process_image(image: Image) -> Optional[Dict[str, Any]]:
+    """Process an image based on the format."""
+    image_payload: Optional[Dict[str, Any]] = None  # Initialize
+    try:
+        if image.url is not None:
+            image_payload = _process_image_url(image.url)
+
+        elif image.filepath is not None:
+            image_payload = _process_image_path(image.filepath)
+
+        elif image.content is not None:
+            # Pass the format from the Image object
+            image_payload = _process_bytes_image(image.content, image.format)
+
+        else:
+            log_warning(f"Unsupported image format or no data provided: {image}")
+            return None
+
+        if image_payload and image.detail:  # Check if payload was created before adding detail
+            # Ensure image_url key exists before trying to access its sub-dictionary
+            if "image_url" not in image_payload:
+                # Initialize if missing (though unlikely based on helper funcs)
+                image_payload["image_url"] = {}
+            image_payload["image_url"]["detail"] = image.detail
+
+        return image_payload
+
+    except (FileNotFoundError, IsADirectoryError, ValueError) as e:
+        log_error(f"Failed to process image due to invalid input: {str(e)}")
+        return None  # Return None for handled validation errors
+    except Exception as e:
+        log_error(f"An unexpected error occurred while processing image: {str(e)}")
+        # Depending on policy, you might want to return None or re-raise
+        return None  # Return None for unexpected errors as well, preventing crashes
+
+
+def images_to_message(images: Sequence[Image]) -> List[Dict[str, Any]]:
+    """
+    Add images to a message for the model. By default, we use the OpenAI image format but other Models
+    can override this method to use a different image format.
+
+    Args:
+        images: Sequence of images in various formats:
+            - str: base64 encoded image, URL, or file path
+            - Dict: pre-formatted image data
+            - bytes: raw image data
+
+    Returns:
+        Message content with images added in the format expected by the model
+    """
+
+    # Create a default message content with text
+    image_messages: List[Dict[str, Any]] = []
+
+    # Add images to the message content
+    for image in images:
+        try:
+            image_data = process_image(image)
+            if image_data:
+                image_messages.append(image_data)
+        except Exception as e:
+            log_error(f"Failed to process image: {str(e)}")
+            continue
+
+    return image_messages
+
+
+def _format_file_for_message(file: File) -> Optional[Dict[str, Any]]:
+    """
+    Add a document url, base64 encoded content or OpenAI file to a message.
+    """
+    import base64
+    import mimetypes
+    from pathlib import Path
+
+    # Case 1: Document is a URL
+    if file.url is not None:
+        from urllib.parse import urlparse
+
+        result = file.file_url_content
+        if not result:
+            log_error(f"Failed to fetch file from URL: {file.url}")
+            return None
+        content_bytes, mime_type = result
+        name = Path(urlparse(file.url).path).name or "file"
+        _mime = mime_type or file.mime_type or mimetypes.guess_type(name)[0] or "application/pdf"
+        _encoded = base64.b64encode(content_bytes).decode("utf-8")
+        _data_url = f"data:{_mime};base64,{_encoded}"
+        return {"type": "file", "file": {"filename": name, "file_data": _data_url}}
+
+    # Case 2: Document is a local file path
+    if file.filepath is not None:
+        path = Path(file.filepath)
+        if not path.is_file():
+            log_error(f"File not found: {path}")
+            return None
+        data = path.read_bytes()
+
+        _mime = file.mime_type or mimetypes.guess_type(path.name)[0] or "application/pdf"
+        _encoded = base64.b64encode(data).decode("utf-8")
+        _data_url = f"data:{_mime};base64,{_encoded}"
+        return {"type": "file", "file": {"filename": path.name, "file_data": _data_url}}
+
+    # Case 3: Document is bytes content
+    if file.content is not None:
+        name = getattr(file, "filename", "file")
+        _mime = file.mime_type or mimetypes.guess_type(name)[0] or "application/pdf"
+        _encoded = base64.b64encode(file.content).decode("utf-8")
+        _data_url = f"data:{_mime};base64,{_encoded}"
+        return {"type": "file", "file": {"filename": name, "file_data": _data_url}}
+
+    return None

agno/utils/pickle.py

@@ -21,7 +21,7 @@ def unpickle_object_from_file(file_path: Path, verify_class: Optional[Any] = Non
     import pickle
 
     _obj = None
-    # logger.debug(f"Reading {file_path}")
+    # log_debug(f"Reading {file_path}")
     if file_path.exists() and file_path.is_file():
         _obj = pickle.load(file_path.open("rb"))