agno 2.2.13__py3-none-any.whl

agno/db/__init__.py

@@ -0,0 +1,24 @@
+from agno.db.base import BaseDb, SessionType
+
+__all__ = [
+    "BaseDb",
+    "SessionType",
+]
+
+
+def __getattr__(name: str):
+    """Lazy import for database implementations to avoid forcing all dependencies."""
+    if name == "DynamoDb":
+        from agno.db.dynamo import DynamoDb
+
+        return DynamoDb
+    elif name == "MongoDb":
+        from agno.db.mongo import MongoDb
+
+        return MongoDb
+    elif name == "PostgresDb":
+        from agno.db.postgres import PostgresDb
+
+        return PostgresDb
+    # Add other db implementations as needed
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

agno/db/async_postgres/__init__.py

@@ -0,0 +1,3 @@
+from agno.db.postgres import AsyncPostgresDb
+
+__all__ = ["AsyncPostgresDb"]

agno/db/base.py

@@ -0,0 +1,598 @@
+from abc import ABC, abstractmethod
+from datetime import date
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple, Union
+from uuid import uuid4
+
+from agno.db.schemas import UserMemory
+from agno.db.schemas.culture import CulturalKnowledge
+from agno.db.schemas.evals import EvalFilterType, EvalRunRecord, EvalType
+from agno.db.schemas.knowledge import KnowledgeRow
+from agno.session import Session
+
+
+class SessionType(str, Enum):
+    AGENT = "agent"
+    TEAM = "team"
+    WORKFLOW = "workflow"
+
+
+class BaseDb(ABC):
+    """Base abstract class for all our Database implementations."""
+
+    def __init__(
+        self,
+        session_table: Optional[str] = None,
+        culture_table: Optional[str] = None,
+        memory_table: Optional[str] = None,
+        metrics_table: Optional[str] = None,
+        eval_table: Optional[str] = None,
+        knowledge_table: Optional[str] = None,
+        id: Optional[str] = None,
+    ):
+        self.id = id or str(uuid4())
+        self.session_table_name = session_table or "agno_sessions"
+        self.culture_table_name = culture_table or "agno_culture"
+        self.memory_table_name = memory_table or "agno_memories"
+        self.metrics_table_name = metrics_table or "agno_metrics"
+        self.eval_table_name = eval_table or "agno_eval_runs"
+        self.knowledge_table_name = knowledge_table or "agno_knowledge"
+
+    @abstractmethod
+    def table_exists(self, table_name: str) -> bool:
+        raise NotImplementedError
+
+    def _create_all_tables(self) -> None:
+        """Create all tables for this database."""
+        pass
+
+    # --- Sessions ---
+    @abstractmethod
+    def delete_session(self, session_id: str) -> bool:
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_sessions(self, session_ids: List[str]) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_session(
+        self,
+        session_id: str,
+        session_type: SessionType,
+        user_id: Optional[str] = None,
+        deserialize: Optional[bool] = True,
+    ) -> Optional[Union[Session, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_sessions(
+        self,
+        session_type: SessionType,
+        user_id: Optional[str] = None,
+        component_id: Optional[str] = None,
+        session_name: Optional[str] = None,
+        start_timestamp: Optional[int] = None,
+        end_timestamp: Optional[int] = None,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+        deserialize: Optional[bool] = True,
+    ) -> Union[List[Session], Tuple[List[Dict[str, Any]], int]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def rename_session(
+        self,
+        session_id: str,
+        session_type: SessionType,
+        session_name: str,
+        deserialize: Optional[bool] = True,
+    ) -> Optional[Union[Session, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def upsert_session(
+        self, session: Session, deserialize: Optional[bool] = True
+    ) -> Optional[Union[Session, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def upsert_sessions(
+        self,
+        sessions: List[Session],
+        deserialize: Optional[bool] = True,
+        preserve_updated_at: bool = False,
+    ) -> List[Union[Session, Dict[str, Any]]]:
+        """Bulk upsert multiple sessions for improved performance on large datasets."""
+        raise NotImplementedError
+
+    # --- Memory ---
+    @abstractmethod
+    def clear_memories(self) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_user_memory(self, memory_id: str, user_id: Optional[str] = None) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_user_memories(self, memory_ids: List[str], user_id: Optional[str] = None) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_all_memory_topics(self, user_id: Optional[str] = None) -> List[str]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_user_memory(
+        self,
+        memory_id: str,
+        deserialize: Optional[bool] = True,
+        user_id: Optional[str] = None,
+    ) -> Optional[Union[UserMemory, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_user_memories(
+        self,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        team_id: Optional[str] = None,
+        topics: Optional[List[str]] = None,
+        search_content: Optional[str] = None,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+        deserialize: Optional[bool] = True,
+    ) -> Union[List[UserMemory], Tuple[List[Dict[str, Any]], int]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_user_memory_stats(
+        self,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        user_id: Optional[str] = None,
+    ) -> Tuple[List[Dict[str, Any]], int]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def upsert_user_memory(
+        self, memory: UserMemory, deserialize: Optional[bool] = True
+    ) -> Optional[Union[UserMemory, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def upsert_memories(
+        self,
+        memories: List[UserMemory],
+        deserialize: Optional[bool] = True,
+        preserve_updated_at: bool = False,
+    ) -> List[Union[UserMemory, Dict[str, Any]]]:
+        """Bulk upsert multiple memories for improved performance on large datasets."""
+        raise NotImplementedError
+
+    # --- Metrics ---
+    @abstractmethod
+    def get_metrics(
+        self,
+        starting_date: Optional[date] = None,
+        ending_date: Optional[date] = None,
+    ) -> Tuple[List[Dict[str, Any]], Optional[int]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def calculate_metrics(self) -> Optional[Any]:
+        raise NotImplementedError
+
+    # --- Knowledge ---
+    @abstractmethod
+    def delete_knowledge_content(self, id: str):
+        """Delete a knowledge row from the database.
+
+        Args:
+            id (str): The ID of the knowledge row to delete.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_knowledge_content(self, id: str) -> Optional[KnowledgeRow]:
+        """Get a knowledge row from the database.
+
+        Args:
+            id (str): The ID of the knowledge row to get.
+
+        Returns:
+            Optional[KnowledgeRow]: The knowledge row, or None if it doesn't exist.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_knowledge_contents(
+        self,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+    ) -> Tuple[List[KnowledgeRow], int]:
+        """Get all knowledge contents from the database.
+
+        Args:
+            limit (Optional[int]): The maximum number of knowledge contents to return.
+            page (Optional[int]): The page number.
+            sort_by (Optional[str]): The column to sort by.
+            sort_order (Optional[str]): The order to sort by.
+
+        Returns:
+            Tuple[List[KnowledgeRow], int]: The knowledge contents and total count.
+
+        Raises:
+            Exception: If an error occurs during retrieval.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def upsert_knowledge_content(self, knowledge_row: KnowledgeRow):
+        """Upsert knowledge content in the database.
+
+        Args:
+            knowledge_row (KnowledgeRow): The knowledge row to upsert.
+
+        Returns:
+            Optional[KnowledgeRow]: The upserted knowledge row, or None if the operation fails.
+        """
+        raise NotImplementedError
+
+    # --- Evals ---
+    @abstractmethod
+    def create_eval_run(self, eval_run: EvalRunRecord) -> Optional[EvalRunRecord]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_eval_runs(self, eval_run_ids: List[str]) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_eval_run(
+        self, eval_run_id: str, deserialize: Optional[bool] = True
+    ) -> Optional[Union[EvalRunRecord, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_eval_runs(
+        self,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        team_id: Optional[str] = None,
+        workflow_id: Optional[str] = None,
+        model_id: Optional[str] = None,
+        filter_type: Optional[EvalFilterType] = None,
+        eval_type: Optional[List[EvalType]] = None,
+        deserialize: Optional[bool] = True,
+    ) -> Union[List[EvalRunRecord], Tuple[List[Dict[str, Any]], int]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def rename_eval_run(
+        self, eval_run_id: str, name: str, deserialize: Optional[bool] = True
+    ) -> Optional[Union[EvalRunRecord, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    # --- Cultural Knowledge ---
+    @abstractmethod
+    def clear_cultural_knowledge(self) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_cultural_knowledge(self, id: str) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_cultural_knowledge(self, id: str) -> Optional[CulturalKnowledge]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_all_cultural_knowledge(
+        self,
+        name: Optional[str] = None,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        team_id: Optional[str] = None,
+    ) -> Optional[List[CulturalKnowledge]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def upsert_cultural_knowledge(self, cultural_knowledge: CulturalKnowledge) -> Optional[CulturalKnowledge]:
+        raise NotImplementedError
+
+
+class AsyncBaseDb(ABC):
+    """Base abstract class for all our async database implementations."""
+
+    def __init__(
+        self,
+        id: Optional[str] = None,
+        session_table: Optional[str] = None,
+        memory_table: Optional[str] = None,
+        metrics_table: Optional[str] = None,
+        eval_table: Optional[str] = None,
+        knowledge_table: Optional[str] = None,
+        culture_table: Optional[str] = None,
+    ):
+        self.id = id or str(uuid4())
+        self.session_table_name = session_table or "agno_sessions"
+        self.memory_table_name = memory_table or "agno_memories"
+        self.metrics_table_name = metrics_table or "agno_metrics"
+        self.eval_table_name = eval_table or "agno_eval_runs"
+        self.knowledge_table_name = knowledge_table or "agno_knowledge"
+        self.culture_table_name = culture_table or "agno_culture"
+
+    @abstractmethod
+    async def table_exists(self, table_name: str) -> bool:
+        """Check if a table with the given name exists in this database.
+
+        Default implementation returns True if the table name is configured.
+        Subclasses should override this to perform actual existence checks.
+
+        Args:
+            table_name: Name of the table to check
+
+        Returns:
+            bool: True if the table exists, False otherwise
+        """
+        raise NotImplementedError
+
+    # --- Sessions ---
+    @abstractmethod
+    async def delete_session(self, session_id: str) -> bool:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_sessions(self, session_ids: List[str]) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_session(
+        self,
+        session_id: str,
+        session_type: SessionType,
+        user_id: Optional[str] = None,
+        deserialize: Optional[bool] = True,
+    ) -> Optional[Union[Session, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_sessions(
+        self,
+        session_type: SessionType,
+        user_id: Optional[str] = None,
+        component_id: Optional[str] = None,
+        session_name: Optional[str] = None,
+        start_timestamp: Optional[int] = None,
+        end_timestamp: Optional[int] = None,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+        deserialize: Optional[bool] = True,
+    ) -> Union[List[Session], Tuple[List[Dict[str, Any]], int]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def rename_session(
+        self,
+        session_id: str,
+        session_type: SessionType,
+        session_name: str,
+        deserialize: Optional[bool] = True,
+    ) -> Optional[Union[Session, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def upsert_session(
+        self, session: Session, deserialize: Optional[bool] = True
+    ) -> Optional[Union[Session, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    # --- Memory ---
+    @abstractmethod
+    async def clear_memories(self) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_user_memory(self, memory_id: str, user_id: Optional[str] = None) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_user_memories(self, memory_ids: List[str], user_id: Optional[str] = None) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_all_memory_topics(self, user_id: Optional[str] = None) -> List[str]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_user_memory(
+        self,
+        memory_id: str,
+        deserialize: Optional[bool] = True,
+        user_id: Optional[str] = None,
+    ) -> Optional[Union[UserMemory, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_user_memories(
+        self,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        team_id: Optional[str] = None,
+        topics: Optional[List[str]] = None,
+        search_content: Optional[str] = None,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+        deserialize: Optional[bool] = True,
+    ) -> Union[List[UserMemory], Tuple[List[Dict[str, Any]], int]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_user_memory_stats(
+        self,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        user_id: Optional[str] = None,
+    ) -> Tuple[List[Dict[str, Any]], int]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def upsert_user_memory(
+        self, memory: UserMemory, deserialize: Optional[bool] = True
+    ) -> Optional[Union[UserMemory, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    # --- Metrics ---
+    @abstractmethod
+    async def get_metrics(
+        self, starting_date: Optional[date] = None, ending_date: Optional[date] = None
+    ) -> Tuple[List[Dict[str, Any]], Optional[int]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def calculate_metrics(self) -> Optional[Any]:
+        raise NotImplementedError
+
+    # --- Knowledge ---
+    @abstractmethod
+    async def delete_knowledge_content(self, id: str):
+        """Delete a knowledge row from the database.
+
+        Args:
+            id (str): The ID of the knowledge row to delete.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_knowledge_content(self, id: str) -> Optional[KnowledgeRow]:
+        """Get a knowledge row from the database.
+
+        Args:
+            id (str): The ID of the knowledge row to get.
+
+        Returns:
+            Optional[KnowledgeRow]: The knowledge row, or None if it doesn't exist.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_knowledge_contents(
+        self,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+    ) -> Tuple[List[KnowledgeRow], int]:
+        """Get all knowledge contents from the database.
+
+        Args:
+            limit (Optional[int]): The maximum number of knowledge contents to return.
+            page (Optional[int]): The page number.
+            sort_by (Optional[str]): The column to sort by.
+            sort_order (Optional[str]): The order to sort by.
+
+        Returns:
+            Tuple[List[KnowledgeRow], int]: The knowledge contents and total count.
+
+        Raises:
+            Exception: If an error occurs during retrieval.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def upsert_knowledge_content(self, knowledge_row: KnowledgeRow):
+        """Upsert knowledge content in the database.
+
+        Args:
+            knowledge_row (KnowledgeRow): The knowledge row to upsert.
+
+        Returns:
+            Optional[KnowledgeRow]: The upserted knowledge row, or None if the operation fails.
+        """
+        raise NotImplementedError
+
+    # --- Evals ---
+    @abstractmethod
+    async def create_eval_run(self, eval_run: EvalRunRecord) -> Optional[EvalRunRecord]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_eval_runs(self, eval_run_ids: List[str]) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_eval_run(
+        self, eval_run_id: str, deserialize: Optional[bool] = True
+    ) -> Optional[Union[EvalRunRecord, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_eval_runs(
+        self,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        team_id: Optional[str] = None,
+        workflow_id: Optional[str] = None,
+        model_id: Optional[str] = None,
+        filter_type: Optional[EvalFilterType] = None,
+        eval_type: Optional[List[EvalType]] = None,
+        deserialize: Optional[bool] = True,
+    ) -> Union[List[EvalRunRecord], Tuple[List[Dict[str, Any]], int]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def rename_eval_run(
+        self, eval_run_id: str, name: str, deserialize: Optional[bool] = True
+    ) -> Optional[Union[EvalRunRecord, Dict[str, Any]]]:
+        raise NotImplementedError
+
+    # --- Cultural Notions ---
+    @abstractmethod
+    async def clear_cultural_knowledge(self) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_cultural_knowledge(self, id: str) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_cultural_knowledge(self, id: str) -> Optional[CulturalKnowledge]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_all_cultural_knowledge(
+        self,
+        name: Optional[str] = None,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        team_id: Optional[str] = None,
+    ) -> Optional[List[CulturalKnowledge]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def upsert_cultural_knowledge(self, cultural_knowledge: CulturalKnowledge) -> Optional[CulturalKnowledge]:
+        raise NotImplementedError

agno/db/dynamo/__init__.py

@@ -0,0 +1,3 @@
+from agno.db.dynamo.dynamo import DynamoDb
+
+__all__ = ["DynamoDb"]