agno 2.1.9__py3-none-any.whl → 2.2.0__py3-none-any.whl

agno/db/async_postgres/async_postgres.py

@@ -9,12 +9,15 @@ from agno.db.async_postgres.utils import (
     bulk_upsert_metrics,
     calculate_date_metrics,
     create_schema,
+    deserialize_cultural_knowledge,
     fetch_all_sessions_data,
     get_dates_to_calculate_metrics_for,
     is_table_available,
     is_valid_table,
+    serialize_cultural_knowledge,
 )
 from agno.db.base import AsyncBaseDb, SessionType
+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.db.schemas.memory import UserMemory
@@ -43,6 +46,7 @@ class AsyncPostgresDb(AsyncBaseDb):
         metrics_table: Optional[str] = None,
         eval_table: Optional[str] = None,
         knowledge_table: Optional[str] = None,
+        culture_table: Optional[str] = None,
     ):
         """
         Async interface for interacting with a PostgreSQL database.
@@ -62,6 +66,7 @@ class AsyncPostgresDb(AsyncBaseDb):
             metrics_table (Optional[str]): Name of the table to store metrics.
             eval_table (Optional[str]): Name of the table to store evaluation runs data.
             knowledge_table (Optional[str]): Name of the table to store knowledge content.
+            culture_table (Optional[str]): Name of the table to store cultural knowledge.
 
         Raises:
             ValueError: If neither db_url nor db_engine is provided.
@@ -74,6 +79,7 @@ class AsyncPostgresDb(AsyncBaseDb):
             metrics_table=metrics_table,
             eval_table=eval_table,
             knowledge_table=knowledge_table,
+            culture_table=culture_table,
         )
 
         _engine: Optional[AsyncEngine] = db_engine
@@ -212,6 +218,13 @@ class AsyncPostgresDb(AsyncBaseDb):
                 )
             return self.knowledge_table
 
+        if table_type == "culture":
+            if not hasattr(self, "culture_table"):
+                self.culture_table = await self._get_or_create_table(
+                    table_name=self.culture_table_name, table_type="culture", db_schema=self.db_schema
+                )
+            return self.culture_table
+
         raise ValueError(f"Unknown table type: {table_type}")
 
     async def _get_or_create_table(self, table_name: str, table_type: str, db_schema: str) -> Table:
@@ -886,6 +899,225 @@ class AsyncPostgresDb(AsyncBaseDb):
         except Exception as e:
             log_warning(f"Exception deleting all memories: {e}")
 
+    # -- Cultural Knowledge methods --
+    async def clear_cultural_knowledge(self) -> None:
+        """Delete all cultural knowledge from the database.
+
+        Raises:
+            Exception: If an error occurs during deletion.
+        """
+        try:
+            table = await self._get_table(table_type="culture")
+
+            async with self.async_session_factory() as sess, sess.begin():
+                await sess.execute(table.delete())
+
+        except Exception as e:
+            log_warning(f"Exception deleting all cultural knowledge: {e}")
+
+    async def delete_cultural_knowledge(self, id: str) -> None:
+        """Delete cultural knowledge by ID.
+
+        Args:
+            id (str): The ID of the cultural knowledge to delete.
+
+        Raises:
+            Exception: If an error occurs during deletion.
+        """
+        try:
+            table = await self._get_table(table_type="culture")
+
+            async with self.async_session_factory() as sess, sess.begin():
+                stmt = table.delete().where(table.c.id == id)
+                await sess.execute(stmt)
+
+        except Exception as e:
+            log_warning(f"Exception deleting cultural knowledge: {e}")
+            raise e
+
+    async def get_cultural_knowledge(
+        self, id: str, deserialize: Optional[bool] = True
+    ) -> Optional[Union[CulturalKnowledge, Dict[str, Any]]]:
+        """Get cultural knowledge by ID.
+
+        Args:
+            id (str): The ID of the cultural knowledge to retrieve.
+            deserialize (Optional[bool]): Whether to deserialize to CulturalKnowledge object. Defaults to True.
+
+        Returns:
+            Optional[Union[CulturalKnowledge, Dict[str, Any]]]: The cultural knowledge if found, None otherwise.
+
+        Raises:
+            Exception: If an error occurs during retrieval.
+        """
+        try:
+            table = await self._get_table(table_type="culture")
+
+            async with self.async_session_factory() as sess:
+                stmt = select(table).where(table.c.id == id)
+                result = await sess.execute(stmt)
+                row = result.fetchone()
+
+                if row is None:
+                    return None
+
+                db_row = dict(row._mapping)
+
+                if not deserialize:
+                    return db_row
+
+                return deserialize_cultural_knowledge(db_row)
+
+        except Exception as e:
+            log_warning(f"Exception reading cultural knowledge: {e}")
+            raise e
+
+    async def get_all_cultural_knowledge(
+        self,
+        agent_id: Optional[str] = None,
+        team_id: Optional[str] = None,
+        name: 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[CulturalKnowledge], Tuple[List[Dict[str, Any]], int]]:
+        """Get all cultural knowledge with filtering and pagination.
+
+        Args:
+            agent_id (Optional[str]): Filter by agent ID.
+            team_id (Optional[str]): Filter by team ID.
+            name (Optional[str]): Filter by name (case-insensitive partial match).
+            limit (Optional[int]): Maximum number of results to return.
+            page (Optional[int]): Page number for pagination.
+            sort_by (Optional[str]): Field to sort by.
+            sort_order (Optional[str]): Sort order ('asc' or 'desc').
+            deserialize (Optional[bool]): Whether to deserialize to CulturalKnowledge objects. Defaults to True.
+
+        Returns:
+            Union[List[CulturalKnowledge], Tuple[List[Dict[str, Any]], int]]:
+                - When deserialize=True: List of CulturalKnowledge objects
+                - When deserialize=False: Tuple with list of dictionaries and total count
+
+        Raises:
+            Exception: If an error occurs during retrieval.
+        """
+        try:
+            table = await self._get_table(table_type="culture")
+
+            async with self.async_session_factory() as sess:
+                # Build query with filters
+                stmt = select(table)
+                if agent_id is not None:
+                    stmt = stmt.where(table.c.agent_id == agent_id)
+                if team_id is not None:
+                    stmt = stmt.where(table.c.team_id == team_id)
+                if name is not None:
+                    stmt = stmt.where(table.c.name.ilike(f"%{name}%"))
+
+                # Get total count
+                count_stmt = select(func.count()).select_from(stmt.alias())
+                total_count_result = await sess.execute(count_stmt)
+                total_count = total_count_result.scalar() or 0
+
+                # Apply sorting
+                stmt = apply_sorting(stmt, table, sort_by, sort_order)
+
+                # Apply pagination
+                if limit is not None:
+                    stmt = stmt.limit(limit)
+                    if page is not None:
+                        stmt = stmt.offset((page - 1) * limit)
+
+                # Execute query
+                result = await sess.execute(stmt)
+                rows = result.fetchall()
+
+                db_rows = [dict(row._mapping) for row in rows]
+
+                if not deserialize:
+                    return db_rows, total_count
+
+                return [deserialize_cultural_knowledge(row) for row in db_rows]
+
+        except Exception as e:
+            log_warning(f"Exception reading all cultural knowledge: {e}")
+            raise e
+
+    async def upsert_cultural_knowledge(
+        self, cultural_knowledge: CulturalKnowledge, deserialize: Optional[bool] = True
+    ) -> Optional[Union[CulturalKnowledge, Dict[str, Any]]]:
+        """Upsert cultural knowledge in the database.
+
+        Args:
+            cultural_knowledge (CulturalKnowledge): The cultural knowledge to upsert.
+            deserialize (Optional[bool]): Whether to deserialize the result. Defaults to True.
+
+        Returns:
+            Optional[Union[CulturalKnowledge, Dict[str, Any]]]: The upserted cultural knowledge.
+
+        Raises:
+            Exception: If an error occurs during upsert.
+        """
+        try:
+            table = await self._get_table(table_type="culture")
+
+            # Generate ID if not present
+            if cultural_knowledge.id is None:
+                cultural_knowledge.id = str(uuid4())
+
+            # Serialize content, categories, and notes into a JSON dict for DB storage
+            content_dict = serialize_cultural_knowledge(cultural_knowledge)
+
+            async with self.async_session_factory() as sess, sess.begin():
+                # Use PostgreSQL-specific insert with on_conflict_do_update
+                insert_stmt = postgresql.insert(table).values(
+                    id=cultural_knowledge.id,
+                    name=cultural_knowledge.name,
+                    summary=cultural_knowledge.summary,
+                    content=content_dict if content_dict else None,
+                    metadata=cultural_knowledge.metadata,
+                    input=cultural_knowledge.input,
+                    created_at=cultural_knowledge.created_at,
+                    updated_at=int(time.time()),
+                    agent_id=cultural_knowledge.agent_id,
+                    team_id=cultural_knowledge.team_id,
+                )
+
+                # Update all fields except id on conflict
+                update_dict = {
+                    "name": cultural_knowledge.name,
+                    "summary": cultural_knowledge.summary,
+                    "content": content_dict if content_dict else None,
+                    "metadata": cultural_knowledge.metadata,
+                    "input": cultural_knowledge.input,
+                    "updated_at": int(time.time()),
+                    "agent_id": cultural_knowledge.agent_id,
+                    "team_id": cultural_knowledge.team_id,
+                }
+                upsert_stmt = insert_stmt.on_conflict_do_update(index_elements=["id"], set_=update_dict).returning(
+                    table
+                )
+
+                result = await sess.execute(upsert_stmt)
+                row = result.fetchone()
+
+                if row is None:
+                    return None
+
+                db_row = dict(row._mapping)
+
+            if not deserialize:
+                return db_row
+
+            # Deserialize from DB format to model format
+            return deserialize_cultural_knowledge(db_row)
+
+        except Exception as e:
+            log_warning(f"Exception upserting cultural knowledge: {e}")
+            raise e
+
     async def get_user_memory_stats(
         self, limit: Optional[int] = None, page: Optional[int] = None
     ) -> Tuple[List[Dict[str, Any]], int]:

agno/db/async_postgres/schemas.py

@@ -3,6 +3,7 @@
 from typing import Any
 
 try:
+    from sqlalchemy.dialects.postgresql import JSONB
     from sqlalchemy.types import JSON, BigInteger, Boolean, Date, String
 except ImportError:
     raise ImportError("`sqlalchemy` not installed. Please install it using `pip install sqlalchemy`")
@@ -98,6 +99,19 @@ METRICS_TABLE_SCHEMA = {
     ],
 }
 
+CULTURAL_KNOWLEDGE_TABLE_SCHEMA = {
+    "id": {"type": String, "primary_key": True, "nullable": False},
+    "name": {"type": String, "nullable": False, "index": True},
+    "summary": {"type": String, "nullable": True},
+    "content": {"type": JSONB, "nullable": True},
+    "metadata": {"type": JSONB, "nullable": True},
+    "input": {"type": String, "nullable": True},
+    "created_at": {"type": BigInteger, "nullable": True},
+    "updated_at": {"type": BigInteger, "nullable": True},
+    "agent_id": {"type": String, "nullable": True, "index": True},
+    "team_id": {"type": String, "nullable": True, "index": True},
+}
+
 
 def get_table_schema_definition(table_type: str) -> dict[str, Any]:
     """
@@ -115,6 +129,7 @@ def get_table_schema_definition(table_type: str) -> dict[str, Any]:
         "metrics": METRICS_TABLE_SCHEMA,
         "memories": MEMORY_TABLE_SCHEMA,
         "knowledge": KNOWLEDGE_TABLE_SCHEMA,
+        "culture": CULTURAL_KNOWLEDGE_TABLE_SCHEMA,
     }
 
     schema = schemas.get(table_type, {})

agno/db/async_postgres/utils.py

@@ -8,6 +8,7 @@ from uuid import uuid4
 from sqlalchemy.ext.asyncio import AsyncEngine
 
 from agno.db.async_postgres.schemas import get_table_schema_definition
+from agno.db.schemas.culture import CulturalKnowledge
 from agno.utils.log import log_debug, log_error, log_warning
 
 try:
@@ -287,3 +288,60 @@ def get_dates_to_calculate_metrics_for(starting_date: date) -> list[date]:
     if days_diff <= 0:
         return []
     return [starting_date + timedelta(days=x) for x in range(days_diff)]
+
+
+# -- Cultural Knowledge util methods --
+def serialize_cultural_knowledge(cultural_knowledge: CulturalKnowledge) -> Dict[str, Any]:
+    """Serialize a CulturalKnowledge object for database storage.
+
+    Converts the model's separate content, categories, and notes fields
+    into a single JSON dict for the database content column.
+
+    Args:
+        cultural_knowledge (CulturalKnowledge): The cultural knowledge object to serialize.
+
+    Returns:
+        Dict[str, Any]: A dictionary with the content field as JSON containing content, categories, and notes.
+    """
+    content_dict: Dict[str, Any] = {}
+    if cultural_knowledge.content is not None:
+        content_dict["content"] = cultural_knowledge.content
+    if cultural_knowledge.categories is not None:
+        content_dict["categories"] = cultural_knowledge.categories
+    if cultural_knowledge.notes is not None:
+        content_dict["notes"] = cultural_knowledge.notes
+
+    return content_dict if content_dict else {}
+
+
+def deserialize_cultural_knowledge(db_row: Dict[str, Any]) -> CulturalKnowledge:
+    """Deserialize a database row to a CulturalKnowledge object.
+
+    The database stores content as a JSON dict containing content, categories, and notes.
+    This method extracts those fields and converts them back to the model format.
+
+    Args:
+        db_row (Dict[str, Any]): The database row as a dictionary.
+
+    Returns:
+        CulturalKnowledge: The cultural knowledge object.
+    """
+    # Extract content, categories, and notes from the JSON content field
+    content_json = db_row.get("content", {}) or {}
+
+    return CulturalKnowledge.from_dict(
+        {
+            "id": db_row.get("id"),
+            "name": db_row.get("name"),
+            "summary": db_row.get("summary"),
+            "content": content_json.get("content"),
+            "categories": content_json.get("categories"),
+            "notes": content_json.get("notes"),
+            "metadata": db_row.get("metadata"),
+            "input": db_row.get("input"),
+            "created_at": db_row.get("created_at"),
+            "updated_at": db_row.get("updated_at"),
+            "agent_id": db_row.get("agent_id"),
+            "team_id": db_row.get("team_id"),
+        }
+    )

agno/db/base.py

@@ -5,6 +5,7 @@ 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
@@ -22,6 +23,7 @@ class BaseDb(ABC):
     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,
@@ -30,6 +32,7 @@ class BaseDb(ABC):
     ):
         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"
@@ -73,7 +76,11 @@ class BaseDb(ABC):
 
     @abstractmethod
     def rename_session(
-        self, session_id: str, session_type: SessionType, session_name: str, deserialize: Optional[bool] = True
+        self,
+        session_id: str,
+        session_type: SessionType,
+        session_name: str,
+        deserialize: Optional[bool] = True,
     ) -> Optional[Union[Session, Dict[str, Any]]]:
         raise NotImplementedError
 
@@ -85,13 +92,15 @@ class BaseDb(ABC):
 
     @abstractmethod
     def upsert_sessions(
-        self, sessions: List[Session], deserialize: Optional[bool] = True, preserve_updated_at: bool = False
+        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
@@ -150,7 +159,10 @@ class BaseDb(ABC):
 
     @abstractmethod
     def upsert_memories(
-        self, memories: List[UserMemory], deserialize: Optional[bool] = True, preserve_updated_at: bool = False
+        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
@@ -264,6 +276,36 @@ class BaseDb(ABC):
     ) -> 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."""
@@ -276,6 +318,7 @@ class AsyncBaseDb(ABC):
         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"
@@ -283,6 +326,7 @@ class AsyncBaseDb(ABC):
         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"
 
     # --- Sessions ---
     @abstractmethod
@@ -322,7 +366,11 @@ class AsyncBaseDb(ABC):
 
     @abstractmethod
     async def rename_session(
-        self, session_id: str, session_type: SessionType, session_name: str, deserialize: Optional[bool] = True
+        self,
+        session_id: str,
+        session_type: SessionType,
+        session_name: str,
+        deserialize: Optional[bool] = True,
     ) -> Optional[Union[Session, Dict[str, Any]]]:
         raise NotImplementedError
 
@@ -333,7 +381,6 @@ class AsyncBaseDb(ABC):
         raise NotImplementedError
 
     # --- Memory ---
-
     @abstractmethod
     async def clear_memories(self) -> None:
         raise NotImplementedError
@@ -496,3 +543,33 @@ class AsyncBaseDb(ABC):
         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