agno 2.0.0rc2__py3-none-any.whl → 2.3.0__py3-none-any.whl

agno/media.py

@@ -1,343 +1,349 @@
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple, Union
+from uuid import uuid4
 
 from pydantic import BaseModel, field_validator, model_validator
 
 
-class Media(BaseModel):
-    id: str
-    original_prompt: Optional[str] = None
-    revised_prompt: Optional[str] = None
+class Image(BaseModel):
+    """Unified Image class for all use cases (input, output, artifacts)"""
 
+    # Core content fields (exactly one required)
+    url: Optional[str] = None  # Remote location
+    filepath: Optional[Union[Path, str]] = None  # Local file path
+    content: Optional[bytes] = None  # Raw image bytes (standardized to bytes)
 
-class VideoArtifact(Media):
-    url: Optional[str] = None  # Remote location for file (if no inline content)
-    content: Optional[Union[str, bytes]] = None  # type: ignore
-    mime_type: Optional[str] = None  # MIME type of the video content
-    eta: Optional[str] = None
-    length: Optional[str] = None
+    # Metadata fields
+    id: Optional[str] = None  # For tracking/referencing
+    format: Optional[str] = None  # E.g. 'png', 'jpeg', 'webp', 'gif'
+    mime_type: Optional[str] = None  # E.g. 'image/png', 'image/jpeg'
 
-    def to_dict(self) -> Dict[str, Any]:
-        response_dict = {
-            "id": self.id,
-            "url": self.url,
-            "content": self.content
-            if isinstance(self.content, str)
-            else self.content.decode("utf-8")
-            if self.content
-            else None,
-            "mime_type": self.mime_type,
-            "eta": self.eta,
-        }
-        return {k: v for k, v in response_dict.items() if v is not None}
+    # Input-specific fields
+    detail: Optional[str] = (
+        None  # low, medium, high or auto (per OpenAI spec https://platform.openai.com/docs/guides/vision?lang=node#low-or-high-fidelity-image-understanding)
+    )
 
+    # Output-specific fields (from tools/LLMs)
+    original_prompt: Optional[str] = None  # Original generation prompt
+    revised_prompt: Optional[str] = None  # Revised generation prompt
+    alt_text: Optional[str] = None  # Alt text description
 
-class ImageArtifact(Media):
-    url: Optional[str] = None  # Remote location for file
-    content: Optional[bytes] = None  # Actual image bytes content
-    mime_type: Optional[str] = None
-    alt_text: Optional[str] = None
+    @model_validator(mode="before")
+    def validate_and_normalize_content(cls, data: Any):
+        """Ensure exactly one content source and normalize to bytes"""
+        if isinstance(data, dict):
+            url = data.get("url")
+            filepath = data.get("filepath")
+            content = data.get("content")
+
+            # Count non-None sources
+            sources = [x for x in [url, filepath, content] if x is not None]
+            if len(sources) == 0:
+                raise ValueError("One of 'url', 'filepath', or 'content' must be provided")
+            elif len(sources) > 1:
+                raise ValueError("Only one of 'url', 'filepath', or 'content' should be provided")
+
+            # Auto-generate ID if not provided
+            if data.get("id") is None:
+                data["id"] = str(uuid4())
 
-    def _normalise_content(self) -> Optional[Union[str, bytes]]:
-        if self.content is None:
-            return None
-        content_normalised: Union[str, bytes] = self.content
-        if content_normalised and isinstance(content_normalised, bytes):
-            from base64 import b64encode
+        return data
 
-            try:
-                # First try to decode as UTF-8
-                content_normalised = content_normalised.decode("utf-8")  # type: ignore
-            except UnicodeDecodeError:
-                # Fallback to base64 encoding for binary content
-                content_normalised = b64encode(bytes(content_normalised)).decode("utf-8")  # type: ignore
-            except Exception:
-                # Last resort: try to convert to base64
-                try:
-                    content_normalised = b64encode(bytes(content_normalised)).decode("utf-8")  # type: ignore
-                except Exception:
-                    pass
-        return content_normalised
+    def get_content_bytes(self) -> Optional[bytes]:
+        """Get image content as raw bytes, loading from URL/file if needed"""
+        if self.content:
+            return self.content
+        elif self.url:
+            import httpx
 
-    def to_dict(self) -> Dict[str, Any]:
-        content_normalised = self._normalise_content()
+            return httpx.get(self.url).content
+        elif self.filepath:
+            with open(self.filepath, "rb") as f:
+                return f.read()
+        return None
+
+    def to_base64(self) -> Optional[str]:
+        """Convert content to base64 string for transmission/storage"""
+        content_bytes = self.get_content_bytes()
+        if content_bytes:
+            import base64
 
-        response_dict = {
-            "id": self.id,
-            "url": self.url,
-            "content": content_normalised,
-            "mime_type": self.mime_type,
-            "alt_text": self.alt_text,
-        }
-        return {k: v for k, v in response_dict.items() if v is not None}
+            return base64.b64encode(content_bytes).decode("utf-8")
+        return None
 
+    @classmethod
+    def from_base64(
+        cls,
+        base64_content: str,
+        id: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        format: Optional[str] = None,
+        **kwargs,
+    ) -> "Image":
+        """Create Image from base64 content"""
+        import base64
 
-class AudioArtifact(Media):
-    url: Optional[str] = None  # Remote location for file
-    base64_audio: Optional[str] = None  # Base64-encoded audio data
-    length: Optional[str] = None
-    mime_type: Optional[str] = None
+        try:
+            content_bytes = base64.b64decode(base64_content)
+        except Exception:
+            content_bytes = base64_content.encode("utf-8")
 
-    @model_validator(mode="before")
-    def validate_exclusive_audio(cls, data: Any):
-        """
-        Ensure that either `url` or `base64_audio` is provided, but not both.
-        """
-        if data.get("url") and data.get("base64_audio"):
-            raise ValueError("Provide either `url` or `base64_audio`, not both.")
-        if not data.get("url") and not data.get("base64_audio"):
-            raise ValueError("Either `url` or `base64_audio` must be provided.")
-        return data
+        return cls(content=content_bytes, id=id or str(uuid4()), mime_type=mime_type, format=format, **kwargs)
 
-    def to_dict(self) -> Dict[str, Any]:
-        response_dict = {
+    def to_dict(self, include_base64_content: bool = True) -> Dict[str, Any]:
+        """Convert to dict, optionally including base64-encoded content"""
+        result = {
             "id": self.id,
             "url": self.url,
-            "content": self.base64_audio,
+            "filepath": str(self.filepath) if self.filepath else None,
+            "format": self.format,
             "mime_type": self.mime_type,
-            "length": self.length,
+            "detail": self.detail,
+            "original_prompt": self.original_prompt,
+            "revised_prompt": self.revised_prompt,
+            "alt_text": self.alt_text,
         }
-        return {k: v for k, v in response_dict.items() if v is not None}
-
-
-class Video(BaseModel):
-    filepath: Optional[Union[Path, str]] = None  # Absolute local location for video
-    content: Optional[Any] = None  # Actual video bytes content
-    url: Optional[str] = None  # Remote location for video
-    format: Optional[str] = None  # E.g. `mp4`, `mov`, `avi`, `mkv`, `webm`, `flv`, `mpeg`, `mpg`, `wmv`, `three_gp`
-
-    @model_validator(mode="before")
-    def validate_data(cls, data: Any):
-        """
-        Ensure that exactly one of `filepath`, or `content` or `url` is provided.
-        Also converts content to bytes if it's a string.
-        """
-        # Extract the values from the input data
-        filepath = data.get("filepath")
-        content = data.get("content")
-        url = data.get("url")
-
-        # Convert and decompress content to bytes if it's a string
-        if content and isinstance(content, str):
-            import base64
-
-            try:
-                import zlib
-
-                decoded_content = base64.b64decode(content)
-                content = zlib.decompress(decoded_content)
-            except Exception:
-                content = base64.b64decode(content).decode("utf-8")
-        data["content"] = content
-
-        # Count how many fields are set (not None)
-        count = len([field for field in [filepath, content, url] if field is not None])
-
-        if count == 0:
-            raise ValueError("One of `filepath` or `content` or `url` must be provided.")
-        elif count > 1:
-            raise ValueError("Only one of `filepath` or `content` or `url` should be provided.")
-
-        return data
-
-    def to_dict(self) -> Dict[str, Any]:
-        import base64
-        import zlib
 
-        response_dict = {
-            "content": base64.b64encode(
-                zlib.compress(self.content) if isinstance(self.content, bytes) else self.content.encode("utf-8")
-            ).decode("utf-8")
-            if self.content
-            else None,
-            "filepath": self.filepath,
-            "format": self.format,
-        }
-        return {k: v for k, v in response_dict.items() if v is not None}
+        if include_base64_content and self.content:
+            result["content"] = self.to_base64()
 
-    @classmethod
-    def from_artifact(cls, artifact: VideoArtifact) -> "Video":
-        return cls(url=artifact.url, content=artifact.content, format=artifact.mime_type)
+        return {k: v for k, v in result.items() if v is not None}
 
 
 class Audio(BaseModel):
-    content: Optional[Any] = None  # Actual audio bytes content
-    filepath: Optional[Union[Path, str]] = None  # Absolute local location for audio
-    url: Optional[str] = None  # Remote location for audio
-    format: Optional[str] = None
+    """Unified Audio class for all use cases (input, output, artifacts)"""
 
-    @model_validator(mode="before")
-    def validate_data(cls, data: Any):
-        """
-        Ensure that exactly one of `filepath`, or `content` is provided.
-        Also converts content to bytes if it's a string.
-        """
-        # Extract the values from the input data
-        filepath = data.get("filepath")
-        content = data.get("content")
-        url = data.get("url")
-
-        # Convert and decompress content to bytes if it's a string
-        if content and isinstance(content, str):
-            import base64
+    # Core content fields (exactly one required)
+    url: Optional[str] = None
+    filepath: Optional[Union[Path, str]] = None
+    content: Optional[bytes] = None  # Raw audio bytes (standardized to bytes)
 
-            try:
-                import zlib
+    # Metadata fields
+    id: Optional[str] = None
+    format: Optional[str] = None  # E.g. 'mp3', 'wav', 'ogg'
+    mime_type: Optional[str] = None  # E.g. 'audio/mpeg', 'audio/wav'
 
-                decoded_content = base64.b64decode(content)
-                content = zlib.decompress(decoded_content)
-            except Exception:
-                content = base64.b64decode(content).decode("utf-8")
-        data["content"] = content
+    # Audio-specific metadata
+    duration: Optional[float] = None  # Duration in seconds
+    sample_rate: Optional[int] = 24000  # Sample rate in Hz
+    channels: Optional[int] = 1  # Number of audio channels
 
-        # Count how many fields are set (not None)
-        count = len([field for field in [filepath, content, url] if field is not None])
+    # Output-specific fields (from LLMs)
+    transcript: Optional[str] = None  # Text transcript of audio
+    expires_at: Optional[int] = None  # Expiration timestamp for temporary URLs
 
-        if count == 0:
-            raise ValueError("One of `filepath` or `content` or `url` must be provided.")
-        elif count > 1:
-            raise ValueError("Only one of `filepath` or `content` or `url` should be provided.")
+    @model_validator(mode="before")
+    def validate_and_normalize_content(cls, data: Any):
+        """Ensure exactly one content source and normalize to bytes"""
+        if isinstance(data, dict):
+            url = data.get("url")
+            filepath = data.get("filepath")
+            content = data.get("content")
+
+            sources = [x for x in [url, filepath, content] if x is not None]
+            if len(sources) == 0:
+                raise ValueError("One of 'url', 'filepath', or 'content' must be provided")
+            elif len(sources) > 1:
+                raise ValueError("Only one of 'url', 'filepath', or 'content' should be provided")
+
+            if data.get("id") is None:
+                data["id"] = str(uuid4())
 
         return data
 
-    @property
-    def audio_url_content(self) -> Optional[bytes]:
-        import httpx
+    def get_content_bytes(self) -> Optional[bytes]:
+        """Get audio content as raw bytes"""
+        if self.content:
+            return self.content
+        elif self.url:
+            import httpx
 
-        if self.url:
             return httpx.get(self.url).content
-        else:
-            return None
-
-    def to_dict(self) -> Dict[str, Any]:
-        import base64
-        import zlib
-
-        response_dict = {
-            "content": base64.b64encode(
-                zlib.compress(self.content) if isinstance(self.content, bytes) else self.content.encode("utf-8")
-            ).decode("utf-8")
-            if self.content
-            else None,
-            "filepath": self.filepath,
-            "format": self.format,
-        }
+        elif self.filepath:
+            with open(self.filepath, "rb") as f:
+                return f.read()
+        return None
+
+    def to_base64(self) -> Optional[str]:
+        """Convert content to base64 string"""
+        content_bytes = self.get_content_bytes()
+        if content_bytes:
+            import base64
 
-        return {k: v for k, v in response_dict.items() if v is not None}
+            return base64.b64encode(content_bytes).decode("utf-8")
+        return None
 
     @classmethod
-    def from_artifact(cls, artifact: AudioArtifact) -> "Audio":
-        return cls(url=artifact.url, content=artifact.base64_audio, format=artifact.mime_type)
-
-
-class AudioResponse(BaseModel):
-    id: Optional[str] = None
-    content: Optional[str] = None  # Base64 encoded
-    expires_at: Optional[int] = None
-    transcript: Optional[str] = None
-
-    mime_type: Optional[str] = None
-    sample_rate: Optional[int] = 24000
-    channels: Optional[int] = 1
-
-    def to_dict(self) -> Dict[str, Any]:
+    def from_base64(
+        cls,
+        base64_content: str,
+        id: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        transcript: Optional[str] = None,
+        expires_at: Optional[int] = None,
+        sample_rate: Optional[int] = 24000,
+        channels: Optional[int] = 1,
+        **kwargs,
+    ) -> "Audio":
+        """Create Audio from base64 content (useful for API responses)"""
         import base64
 
-        response_dict = {
+        try:
+            content_bytes = base64.b64decode(base64_content)
+        except Exception:
+            # If not valid base64, encode as UTF-8 bytes
+            content_bytes = base64_content.encode("utf-8")
+
+        return cls(
+            content=content_bytes,
+            id=id or str(uuid4()),
+            mime_type=mime_type,
+            transcript=transcript,
+            expires_at=expires_at,
+            sample_rate=sample_rate,
+            channels=channels,
+            **kwargs,
+        )
+
+    def to_dict(self, include_base64_content: bool = True) -> Dict[str, Any]:
+        """Convert to dict, optionally including base64-encoded content"""
+        result = {
             "id": self.id,
-            "content": base64.b64encode(self.content).decode("utf-8")
-            if isinstance(self.content, bytes)
-            else self.content,
-            "expires_at": self.expires_at,
-            "transcript": self.transcript,
+            "url": self.url,
+            "filepath": str(self.filepath) if self.filepath else None,
+            "format": self.format,
             "mime_type": self.mime_type,
+            "duration": self.duration,
             "sample_rate": self.sample_rate,
             "channels": self.channels,
+            "transcript": self.transcript,
+            "expires_at": self.expires_at,
         }
-        return {k: v for k, v in response_dict.items() if v is not None}
 
+        if include_base64_content and self.content:
+            result["content"] = self.to_base64()
 
-class Image(BaseModel):
-    url: Optional[str] = None  # Remote location for image
-    filepath: Optional[Union[Path, str]] = None  # Absolute local location for image
-    content: Optional[Any] = None  # Actual image bytes content
-    format: Optional[str] = None  # E.g. `png`, `jpeg`, `webp`, `gif`
-    detail: Optional[str] = (
-        None  # low, medium, high or auto (per OpenAI spec https://platform.openai.com/docs/guides/vision?lang=node#low-or-high-fidelity-image-understanding)
-    )
-    id: Optional[str] = None
+        return {k: v for k, v in result.items() if v is not None}
 
-    @property
-    def image_url_content(self) -> Optional[bytes]:
-        import httpx
 
-        if self.url:
-            return httpx.get(self.url).content
-        else:
-            return None
+class Video(BaseModel):
+    """Unified Video class for all use cases (input, output, artifacts)"""
 
-    @model_validator(mode="before")
-    def validate_data(cls, data: Any):
-        """
-        Ensure that exactly one of `url`, `filepath`, or `content` is provided.
-        Also converts content to bytes if it's a string.
-        """
-        # Extract the values from the input data
-        url = data.get("url")
-        filepath = data.get("filepath")
-        content = data.get("content")
-
-        # Convert and decompress content to bytes if it's a string
-        if content and isinstance(content, str):
-            import base64
+    # Core content fields (exactly one required)
+    url: Optional[str] = None
+    filepath: Optional[Union[Path, str]] = None
+    content: Optional[bytes] = None  # Raw video bytes (standardized to bytes)
 
-            try:
-                import zlib
+    # Metadata fields
+    id: Optional[str] = None
+    format: Optional[str] = None  # E.g. 'mp4', 'mov', 'avi', 'webm'
+    mime_type: Optional[str] = None  # E.g. 'video/mp4', 'video/quicktime'
 
-                decoded_content = base64.b64decode(content)
-                content = zlib.decompress(decoded_content)
-            except Exception:
-                content = base64.b64decode(content).decode("utf-8")
-        data["content"] = content
+    # Video-specific metadata
+    duration: Optional[float] = None  # Duration in seconds
+    width: Optional[int] = None  # Video width in pixels
+    height: Optional[int] = None  # Video height in pixels
+    fps: Optional[float] = None  # Frames per second
 
-        # Count how many fields are set (not None)
-        count = len([field for field in [url, filepath, content] if field is not None])
+    # Output-specific fields (from tools)
+    eta: Optional[str] = None  # Estimated time for generation
+    original_prompt: Optional[str] = None
+    revised_prompt: Optional[str] = None
 
-        if count == 0:
-            raise ValueError("One of `url`, `filepath`, or `content` must be provided.")
-        elif count > 1:
-            raise ValueError("Only one of `url`, `filepath`, or `content` should be provided.")
+    @model_validator(mode="before")
+    def validate_and_normalize_content(cls, data: Any):
+        """Ensure exactly one content source and normalize to bytes"""
+        if isinstance(data, dict):
+            url = data.get("url")
+            filepath = data.get("filepath")
+            content = data.get("content")
+
+            sources = [x for x in [url, filepath, content] if x is not None]
+            if len(sources) == 0:
+                raise ValueError("One of 'url', 'filepath', or 'content' must be provided")
+            elif len(sources) > 1:
+                raise ValueError("Only one of 'url', 'filepath', or 'content' should be provided")
+
+            if data.get("id") is None:
+                data["id"] = str(uuid4())
 
         return data
 
-    def to_dict(self) -> Dict[str, Any]:
+    def get_content_bytes(self) -> Optional[bytes]:
+        """Get video content as raw bytes"""
+        if self.content:
+            return self.content
+        elif self.url:
+            import httpx
+
+            return httpx.get(self.url).content
+        elif self.filepath:
+            with open(self.filepath, "rb") as f:
+                return f.read()
+        return None
+
+    def to_base64(self) -> Optional[str]:
+        """Convert content to base64 string"""
+        content_bytes = self.get_content_bytes()
+        if content_bytes:
+            import base64
+
+            return base64.b64encode(content_bytes).decode("utf-8")
+        return None
+
+    @classmethod
+    def from_base64(
+        cls,
+        base64_content: str,
+        id: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        format: Optional[str] = None,
+        **kwargs,
+    ) -> "Video":
+        """Create Image from base64 content"""
         import base64
-        import zlib
 
-        response_dict = {
-            "content": base64.b64encode(
-                zlib.compress(self.content) if isinstance(self.content, bytes) else self.content.encode("utf-8")
-            ).decode("utf-8")
-            if self.content
-            else None,
-            "filepath": self.filepath,
+        try:
+            content_bytes = base64.b64decode(base64_content)
+        except Exception:
+            content_bytes = base64_content.encode("utf-8")
+
+        return cls(content=content_bytes, id=id or str(uuid4()), mime_type=mime_type, format=format, **kwargs)
+
+    def to_dict(self, include_base64_content: bool = True) -> Dict[str, Any]:
+        """Convert to dict, optionally including base64-encoded content"""
+        result = {
+            "id": self.id,
             "url": self.url,
-            "detail": self.detail,
+            "filepath": str(self.filepath) if self.filepath else None,
+            "format": self.format,
+            "mime_type": self.mime_type,
+            "duration": self.duration,
+            "width": self.width,
+            "height": self.height,
+            "fps": self.fps,
+            "eta": self.eta,
+            "original_prompt": self.original_prompt,
+            "revised_prompt": self.revised_prompt,
         }
 
-        return {k: v for k, v in response_dict.items() if v is not None}
+        if include_base64_content and self.content:
+            result["content"] = self.to_base64()
 
-    @classmethod
-    def from_artifact(cls, artifact: ImageArtifact) -> "Image":
-        return cls(url=artifact.url, content=artifact.content, format=artifact.mime_type)
+        return {k: v for k, v in result.items() if v is not None}
 
 
 class File(BaseModel):
+    id: Optional[str] = None
     url: Optional[str] = None
     filepath: Optional[Union[Path, str]] = None
     # Raw bytes content of a file
     content: Optional[Any] = None
     mime_type: Optional[str] = None
+
+    file_type: Optional[str] = None
+    filename: Optional[str] = None
+    size: Optional[int] = None
     # External file object (e.g. GeminiFile, must be a valid object as expected by the model you are using)
     external: Optional[Any] = None
     format: Optional[str] = None  # E.g. `pdf`, `txt`, `csv`, `xml`, etc.
@@ -363,7 +369,10 @@ class File(BaseModel):
     def valid_mime_types(cls) -> List[str]:
         return [
             "application/pdf",
+            "application/json",
             "application/x-javascript",
+            "application/json",
+            "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
             "text/javascript",
             "application/x-python",
             "text/x-python",
@@ -376,6 +385,29 @@ class File(BaseModel):
             "text/rtf",
         ]
 
+    @classmethod
+    def from_base64(
+        cls,
+        base64_content: str,
+        id: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        filename: Optional[str] = None,
+        name: Optional[str] = None,
+        format: Optional[str] = None,
+    ) -> "File":
+        """Create File from base64 encoded content"""
+        import base64
+
+        content_bytes = base64.b64decode(base64_content)
+        return cls(
+            content=content_bytes,
+            id=id,
+            mime_type=mime_type,
+            filename=filename,
+            name=name,
+            format=format,
+        )
+
     @property
     def file_url_content(self) -> Optional[Tuple[bytes, str]]:
         import httpx
@@ -387,3 +419,44 @@ class File(BaseModel):
             return content, mime_type
         else:
             return None
+
+    def _normalise_content(self) -> Optional[Union[str, bytes]]:
+        if self.content is None:
+            return None
+        content_normalised: Union[str, bytes] = self.content
+        if content_normalised and isinstance(content_normalised, bytes):
+            from base64 import b64encode
+
+            try:
+                if self.mime_type and self.mime_type.startswith("text/"):
+                    content_normalised = content_normalised.decode("utf-8")
+                else:
+                    content_normalised = b64encode(content_normalised).decode("utf-8")
+            except UnicodeDecodeError:
+                if isinstance(self.content, bytes):
+                    content_normalised = b64encode(self.content).decode("utf-8")
+            except Exception:
+                try:
+                    if isinstance(self.content, bytes):
+                        content_normalised = b64encode(self.content).decode("utf-8")
+                except Exception:
+                    pass
+        return content_normalised
+
+    def to_dict(self) -> Dict[str, Any]:
+        content_normalised = self._normalise_content()
+
+        response_dict = {
+            "id": self.id,
+            "url": self.url,
+            "filepath": str(self.filepath) if self.filepath else None,
+            "content": content_normalised,
+            "mime_type": self.mime_type,
+            "file_type": self.file_type,
+            "filename": self.filename,
+            "size": self.size,
+            "external": self.external,
+            "format": self.format,
+            "name": self.name,
+        }
+        return {k: v for k, v in response_dict.items() if v is not None}