agno 2.2.13__py3-none-any.whl → 2.4.3__py3-none-any.whl

agno/learn/utils.py

@@ -0,0 +1,209 @@
+"""
+Learning Machine Utilities
+==========================
+Helper functions for safe data handling.
+
+All functions are designed to never raise exceptions -
+they return None on any failure. This prevents learning
+extraction errors from crashing the main agent.
+"""
+
+from dataclasses import asdict, fields
+from typing import Any, Dict, List, Optional, Type, TypeVar
+
+T = TypeVar("T")
+
+
+def _safe_get(data: Any, key: str, default: Any = None) -> Any:
+    """Safely get a key from dict-like data.
+
+    Args:
+        data: Dict or object with attributes.
+        key: Key or attribute name to get.
+        default: Value to return if not found.
+
+    Returns:
+        The value, or default if not found.
+    """
+    if isinstance(data, dict):
+        return data.get(key, default)
+    return getattr(data, key, default)
+
+
+def _parse_json(data: Any) -> Optional[Dict]:
+    """Parse JSON string to dict, or return dict as-is.
+
+    Args:
+        data: JSON string, dict, or None.
+
+    Returns:
+        Parsed dict, or None if parsing fails.
+    """
+    if data is None:
+        return None
+    if isinstance(data, dict):
+        return data
+    if isinstance(data, str):
+        import json
+
+        try:
+            return json.loads(data)
+        except Exception:
+            return None
+    return None
+
+
+def from_dict_safe(cls: Type[T], data: Any) -> Optional[T]:
+    """Safely create a dataclass instance from dict-like data.
+
+    Works with any dataclass - automatically handles subclass fields.
+    Never raises - returns None on any failure.
+
+    Args:
+        cls: The dataclass type to instantiate.
+        data: Dict, JSON string, or existing instance.
+
+    Returns:
+        Instance of cls, or None if parsing fails.
+
+    Example:
+        >>> profile = from_dict_safe(UserProfile, {"user_id": "123"})
+        >>> profile.user_id
+        '123'
+    """
+    if data is None:
+        return None
+
+    # Already the right type
+    if isinstance(data, cls):
+        return data
+
+    try:
+        # Parse JSON string if needed
+        parsed = _parse_json(data)
+        if parsed is None:
+            return None
+
+        # Get valid field names for this class
+        field_names = {f.name for f in fields(cls)}  # type: ignore
+
+        # Filter to only valid fields
+        kwargs = {k: v for k, v in parsed.items() if k in field_names}
+
+        return cls(**kwargs)
+    except Exception:
+        return None
+
+
+def print_panel(
+    title: str,
+    subtitle: str,
+    lines: List[str],
+    *,
+    empty_message: str = "No data",
+    raw_data: Any = None,
+    raw: bool = False,
+) -> None:
+    """Print formatted panel output for learning stores.
+
+    Uses rich library for formatted output with a bordered panel.
+    Falls back to pprint when raw=True or rich is unavailable.
+
+    Args:
+        title: Panel title (e.g., "User Profile", "Session Context")
+        subtitle: Panel subtitle (e.g., user_id, session_id)
+        lines: Content lines to display inside the panel
+        empty_message: Message shown when lines is empty
+        raw_data: Object to pprint when raw=True
+        raw: If True, use pprint instead of formatted panel
+
+    Example:
+        >>> print_panel(
+        ...     title="User Profile",
+        ...     subtitle="alice@example.com",
+        ...     lines=["Name: Alice", "Memories:", "  [abc123] Loves Python"],
+        ...     raw_data=profile,
+        ... )
+        ╭──────────────── User Profile ─────────────────╮
+        │ Name: Alice                                   │
+        │ Memories:                                     │
+        │   [abc123] Loves Python                       │
+        ╰─────────────── alice@example.com ─────────────╯
+    """
+    if raw and raw_data is not None:
+        from pprint import pprint
+
+        pprint(to_dict_safe(raw_data) or raw_data)
+        return
+
+    try:
+        from rich.console import Console
+        from rich.panel import Panel
+
+        console = Console()
+
+        if not lines:
+            content = f"[dim]{empty_message}[/dim]"
+        else:
+            content = "\n".join(lines)
+
+        panel = Panel(
+            content,
+            title=f"[bold]{title}[/bold]",
+            subtitle=f"[dim]{subtitle}[/dim]",
+            border_style="blue",
+        )
+        console.print(panel)
+
+    except ImportError:
+        # Fallback if rich not installed
+        from pprint import pprint
+
+        print(f"=== {title} ({subtitle}) ===")
+        if not lines:
+            print(f"  {empty_message}")
+        else:
+            for line in lines:
+                print(f"  {line}")
+        print()
+
+
+def to_dict_safe(obj: Any) -> Optional[Dict[str, Any]]:
+    """Safely convert a dataclass to dict.
+
+    Works with any dataclass. Never raises - returns None on failure.
+
+    Args:
+        obj: Dataclass instance to convert.
+
+    Returns:
+        Dict representation, or None if conversion fails.
+
+    Example:
+        >>> profile = UserProfile(user_id="123")
+        >>> to_dict_safe(profile)
+        {'user_id': '123', 'name': None, ...}
+    """
+    if obj is None:
+        return None
+
+    try:
+        # Already a dict
+        if isinstance(obj, dict):
+            return obj
+
+        # Has to_dict method
+        if hasattr(obj, "to_dict"):
+            return obj.to_dict()
+
+        # Is a dataclass
+        if hasattr(obj, "__dataclass_fields__"):
+            return asdict(obj)
+
+        # Has __dict__
+        if hasattr(obj, "__dict__"):
+            return dict(obj.__dict__)
+
+        return None
+    except Exception:
+        return None

agno/media.py

@@ -4,6 +4,8 @@ from uuid import uuid4
 
 from pydantic import BaseModel, field_validator, model_validator
 
+from agno.utils.log import log_error
+
 
 class Image(BaseModel):
     """Unified Image class for all use cases (input, output, artifacts)"""
@@ -395,10 +397,20 @@ class File(BaseModel):
         name: Optional[str] = None,
         format: Optional[str] = None,
     ) -> "File":
-        """Create File from base64 encoded content"""
+        """Create File from base64 encoded content or plain text.
+
+        Handles both base64-encoded binary content and plain text content
+        (which is stored as UTF-8 strings for text/* MIME types).
+        """
         import base64
 
-        content_bytes = base64.b64decode(base64_content)
+        try:
+            content_bytes = base64.b64decode(base64_content)
+        except Exception:
+            # If not valid base64, it might be plain text content (text/csv, text/plain, etc.)
+            # which is stored as UTF-8 strings, not base64
+            content_bytes = base64_content.encode("utf-8")
+
         return cls(
             content=content_bytes,
             id=id,
@@ -413,10 +425,14 @@ class File(BaseModel):
         import httpx
 
         if self.url:
-            response = httpx.get(self.url)
-            content = response.content
-            mime_type = response.headers.get("Content-Type", "").split(";")[0]
-            return content, mime_type
+            try:
+                response = httpx.get(self.url)
+                content = response.content
+                mime_type = response.headers.get("Content-Type", "").split(";")[0]
+                return content, mime_type
+            except Exception:
+                log_error(f"Failed to download file from {self.url}")
+                return None
         else:
             return None
 

agno/memory/__init__.py

@@ -1,3 +1,16 @@
 from agno.memory.manager import MemoryManager, UserMemory
+from agno.memory.strategies import (
+    MemoryOptimizationStrategy,
+    MemoryOptimizationStrategyFactory,
+    MemoryOptimizationStrategyType,
+    SummarizeStrategy,
+)
 
-__all__ = ["MemoryManager", "UserMemory"]
+__all__ = [
+    "MemoryManager",
+    "UserMemory",
+    "MemoryOptimizationStrategy",
+    "MemoryOptimizationStrategyType",
+    "MemoryOptimizationStrategyFactory",
+    "SummarizeStrategy",
+]

agno/memory/manager.py

@@ -1,6 +1,5 @@
 from copy import deepcopy
 from dataclasses import dataclass
-from datetime import datetime
 from os import getenv
 from textwrap import dedent
 from typing import Any, Callable, Dict, List, Literal, Optional, Type, Union
@@ -9,10 +8,16 @@ from pydantic import BaseModel, Field
 
 from agno.db.base import AsyncBaseDb, BaseDb
 from agno.db.schemas import UserMemory
+from agno.memory.strategies import MemoryOptimizationStrategy
+from agno.memory.strategies.types import (
+    MemoryOptimizationStrategyFactory,
+    MemoryOptimizationStrategyType,
+)
 from agno.models.base import Model
 from agno.models.message import Message
 from agno.models.utils import get_model
 from agno.tools.function import Function
+from agno.utils.dttm import now_epoch_s
 from agno.utils.log import (
     log_debug,
     log_error,
@@ -89,9 +94,6 @@ class MemoryManager:
         self.clear_memories = clear_memories
         self.debug_mode = debug_mode
 
-        self._get_models()
-
-    def _get_models(self) -> None:
         if self.model is not None:
             self.model = get_model(self.model)
 
@@ -227,7 +229,7 @@ class MemoryManager:
             memory.user_id = user_id
 
             if not memory.updated_at:
-                memory.updated_at = datetime.now()
+                memory.updated_at = now_epoch_s()
 
             self._upsert_db_memory(memory=memory)
             return memory.memory_id
@@ -255,7 +257,7 @@ class MemoryManager:
                 user_id = "default"
 
             if not memory.updated_at:
-                memory.updated_at = datetime.now()
+                memory.updated_at = now_epoch_s()
 
             memory.memory_id = memory_id
             memory.user_id = user_id
@@ -291,6 +293,74 @@ class MemoryManager:
             log_warning("Memory DB not provided.")
             return None
 
+    def clear_user_memories(self, user_id: Optional[str] = None) -> None:
+        """Clear all memories for a specific user.
+
+        Args:
+            user_id (Optional[str]): The user id to clear memories for. If not provided, clears memories for the "default" user.
+        """
+        if user_id is None:
+            log_warning("Using default user id.")
+            user_id = "default"
+
+        if not self.db:
+            log_warning("Memory DB not provided.")
+            return
+
+        if isinstance(self.db, AsyncBaseDb):
+            raise ValueError(
+                "clear_user_memories() is not supported with an async DB. Please use aclear_user_memories() instead."
+            )
+
+        # TODO: This is inefficient - we fetch all memories just to get their IDs.
+        # Extend delete_user_memories() to accept just user_id and delete all memories
+        # for that user directly without requiring a list of memory_ids.
+        memories = self.get_user_memories(user_id=user_id)
+        if not memories:
+            log_debug(f"No memories found for user {user_id}")
+            return
+
+        # Extract memory IDs
+        memory_ids = [mem.memory_id for mem in memories if mem.memory_id]
+
+        if memory_ids:
+            # Delete all memories in a single batch operation
+            self.db.delete_user_memories(memory_ids=memory_ids, user_id=user_id)
+            log_debug(f"Cleared {len(memory_ids)} memories for user {user_id}")
+
+    async def aclear_user_memories(self, user_id: Optional[str] = None) -> None:
+        """Clear all memories for a specific user (async).
+
+        Args:
+            user_id (Optional[str]): The user id to clear memories for. If not provided, clears memories for the "default" user.
+        """
+        if user_id is None:
+            user_id = "default"
+
+        if not self.db:
+            log_warning("Memory DB not provided.")
+            return
+
+        if isinstance(self.db, AsyncBaseDb):
+            memories = await self.aget_user_memories(user_id=user_id)
+        else:
+            memories = self.get_user_memories(user_id=user_id)
+
+        if not memories:
+            log_debug(f"No memories found for user {user_id}")
+            return
+
+        # Extract memory IDs
+        memory_ids = [mem.memory_id for mem in memories if mem.memory_id]
+
+        if memory_ids:
+            # Delete all memories in a single batch operation
+            if isinstance(self.db, AsyncBaseDb):
+                await self.db.delete_user_memories(memory_ids=memory_ids, user_id=user_id)
+            else:
+                self.db.delete_user_memories(memory_ids=memory_ids, user_id=user_id)
+            log_debug(f"Cleared {len(memory_ids)} memories for user {user_id}")
+
     # -*- Agent Functions
     def create_user_memories(
         self,
@@ -671,7 +741,7 @@ class MemoryManager:
             # If updated_at is None, place at the beginning of the list
             sorted_memories_list = sorted(
                 memories_list,
-                key=lambda memory: memory.updated_at or datetime.min,
+                key=lambda m: m.updated_at if m.updated_at is not None else 0,
             )
         else:
             sorted_memories_list = []
@@ -694,6 +764,7 @@ class MemoryManager:
         if memories is None:
             memories = {}
 
+        MAX_UNIX_TS = 2**63 - 1
         memories_list = memories.get(user_id, [])
         # Sort memories by updated_at timestamp if available
         if memories_list:
@@ -701,7 +772,7 @@ class MemoryManager:
             # If updated_at is None, place at the end of the list
             sorted_memories_list = sorted(
                 memories_list,
-                key=lambda memory: memory.updated_at or datetime.max,
+                key=lambda m: m.updated_at if m.updated_at is not None else MAX_UNIX_TS,
             )
 
         else:
@@ -712,6 +783,150 @@ class MemoryManager:
 
         return sorted_memories_list
 
+    def optimize_memories(
+        self,
+        user_id: Optional[str] = None,
+        strategy: Union[
+            MemoryOptimizationStrategyType, MemoryOptimizationStrategy
+        ] = MemoryOptimizationStrategyType.SUMMARIZE,
+        apply: bool = True,
+    ) -> List[UserMemory]:
+        """Optimize user memories using the specified strategy.
+
+        Args:
+            user_id: User ID to optimize memories for. Defaults to "default".
+            strategy: Optimization strategy. Can be:
+                - Enum: MemoryOptimizationStrategyType.SUMMARIZE
+                - Instance: Custom MemoryOptimizationStrategy instance
+            apply: If True, automatically replace memories in database.
+
+        Returns:
+            List of optimized UserMemory objects.
+        """
+        if user_id is None:
+            user_id = "default"
+
+        if isinstance(self.db, AsyncBaseDb):
+            raise ValueError(
+                "optimize_memories() is not supported with an async DB. Please use aoptimize_memories() instead."
+            )
+
+        # Get user memories
+        memories = self.get_user_memories(user_id=user_id)
+        if not memories:
+            log_debug("No memories to optimize")
+            return []
+
+        # Get strategy instance
+        if isinstance(strategy, MemoryOptimizationStrategyType):
+            strategy_instance = MemoryOptimizationStrategyFactory.create_strategy(strategy)
+        else:
+            # Already a strategy instance
+            strategy_instance = strategy
+
+        # Optimize memories using strategy
+        optimization_model = self.get_model()
+        optimized_memories = strategy_instance.optimize(memories=memories, model=optimization_model)
+
+        # Apply to database if requested
+        if apply:
+            log_debug(f"Applying optimized memories to database for user {user_id}")
+
+            if not self.db:
+                log_warning("Memory DB not provided. Cannot apply optimized memories.")
+                return optimized_memories
+
+            # Clear all existing memories for the user
+            self.clear_user_memories(user_id=user_id)
+
+            # Add all optimized memories
+            for opt_mem in optimized_memories:
+                # Ensure memory has an ID (generate if needed for new memories)
+                if not opt_mem.memory_id:
+                    from uuid import uuid4
+
+                    opt_mem.memory_id = str(uuid4())
+
+                self.db.upsert_user_memory(memory=opt_mem)
+
+        optimized_tokens = strategy_instance.count_tokens(optimized_memories)
+        log_debug(f"Optimization complete. New token count: {optimized_tokens}")
+
+        return optimized_memories
+
+    async def aoptimize_memories(
+        self,
+        user_id: Optional[str] = None,
+        strategy: Union[
+            MemoryOptimizationStrategyType, MemoryOptimizationStrategy
+        ] = MemoryOptimizationStrategyType.SUMMARIZE,
+        apply: bool = True,
+    ) -> List[UserMemory]:
+        """Async version of optimize_memories.
+
+        Args:
+            user_id: User ID to optimize memories for. Defaults to "default".
+            strategy: Optimization strategy. Can be:
+                - Enum: MemoryOptimizationStrategyType.SUMMARIZE
+                - Instance: Custom MemoryOptimizationStrategy instance
+            apply: If True, automatically replace memories in database.
+
+        Returns:
+            List of optimized UserMemory objects.
+        """
+        if user_id is None:
+            user_id = "default"
+
+        # Get user memories - handle both sync and async DBs
+        if isinstance(self.db, AsyncBaseDb):
+            memories = await self.aget_user_memories(user_id=user_id)
+        else:
+            memories = self.get_user_memories(user_id=user_id)
+
+        if not memories:
+            log_debug("No memories to optimize")
+            return []
+
+        # Get strategy instance
+        if isinstance(strategy, MemoryOptimizationStrategyType):
+            strategy_instance = MemoryOptimizationStrategyFactory.create_strategy(strategy)
+        else:
+            # Already a strategy instance
+            strategy_instance = strategy
+
+        # Optimize memories using strategy (async)
+        optimization_model = self.get_model()
+        optimized_memories = await strategy_instance.aoptimize(memories=memories, model=optimization_model)
+
+        # Apply to database if requested
+        if apply:
+            log_debug(f"Optimizing memories for user {user_id}")
+
+            if not self.db:
+                log_warning("Memory DB not provided. Cannot apply optimized memories.")
+                return optimized_memories
+
+            # Clear all existing memories for the user
+            await self.aclear_user_memories(user_id=user_id)
+
+            # Add all optimized memories
+            for opt_mem in optimized_memories:
+                # Ensure memory has an ID (generate if needed for new memories)
+                if not opt_mem.memory_id:
+                    from uuid import uuid4
+
+                    opt_mem.memory_id = str(uuid4())
+
+                if isinstance(self.db, AsyncBaseDb):
+                    await self.db.upsert_user_memory(memory=opt_mem)
+                elif isinstance(self.db, BaseDb):
+                    self.db.upsert_user_memory(memory=opt_mem)
+
+        optimized_tokens = strategy_instance.count_tokens(optimized_memories)
+        log_debug(f"Memory optimization complete. New token count: {optimized_tokens}")
+
+        return optimized_memories
+
     # --Memory Manager Functions--
     def determine_tools_for_model(self, tools: List[Callable]) -> List[Union[Function, dict]]:
         # Have to reset each time, because of different user IDs

agno/memory/strategies/__init__.py

@@ -0,0 +1,15 @@
+"""Memory optimization strategy implementations."""
+
+from agno.memory.strategies.base import MemoryOptimizationStrategy
+from agno.memory.strategies.summarize import SummarizeStrategy
+from agno.memory.strategies.types import (
+    MemoryOptimizationStrategyFactory,
+    MemoryOptimizationStrategyType,
+)
+
+__all__ = [
+    "MemoryOptimizationStrategy",
+    "MemoryOptimizationStrategyFactory",
+    "MemoryOptimizationStrategyType",
+    "SummarizeStrategy",
+]

agno/memory/strategies/base.py

@@ -0,0 +1,66 @@
+from abc import ABC, abstractmethod
+from typing import List
+
+from agno.db.schemas import UserMemory
+from agno.models.base import Model
+from agno.utils.tokens import count_text_tokens
+
+
+class MemoryOptimizationStrategy(ABC):
+    """Abstract base class for memory optimization strategies.
+
+    Subclasses must implement optimize() and aoptimize().
+    get_system_prompt() is optional and only needed for LLM-based strategies.
+    """
+
+    def get_system_prompt(self) -> str:
+        """Get system prompt for this optimization strategy.
+
+        Returns:
+            System prompt string for LLM-based strategies.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def optimize(
+        self,
+        memories: List[UserMemory],
+        model: Model,
+    ) -> List[UserMemory]:
+        """Optimize memories synchronously.
+
+        Args:
+            memories: List of UserMemory objects to optimize
+            model: Model to use for optimization (if needed)
+
+        Returns:
+            List of optimized UserMemory objects
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def aoptimize(
+        self,
+        memories: List[UserMemory],
+        model: Model,
+    ) -> List[UserMemory]:
+        """Optimize memories asynchronously.
+
+        Args:
+            memories: List of UserMemory objects to optimize
+            model: Model to use for optimization (if needed)
+
+        Returns:
+            List of optimized UserMemory objects
+        """
+        raise NotImplementedError
+
+    def count_tokens(self, memories: List[UserMemory]) -> int:
+        """Count total tokens across all memories.
+
+        Args:
+            memories: List of UserMemory objects
+        Returns:
+            Total token count
+        """
+        return sum(count_text_tokens(m.memory or "") for m in memories)