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

agno/db/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},
+    "team_id": {"type": String, "nullable": 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/postgres/utils.py

@@ -8,6 +8,7 @@ from uuid import uuid4
 from sqlalchemy import Engine
 
 from agno.db.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:
@@ -278,3 +279,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_for_db(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_from_db(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/redis/redis.py

@@ -10,14 +10,17 @@ from agno.db.redis.utils import (
     apply_sorting,
     calculate_date_metrics,
     create_index_entries,
+    deserialize_cultural_knowledge_from_db,
     deserialize_data,
     fetch_all_sessions_data,
     generate_redis_key,
     get_all_keys_for_table,
     get_dates_to_calculate_metrics_for,
     remove_index_entries,
+    serialize_cultural_knowledge_for_db,
     serialize_data,
 )
+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
@@ -44,6 +47,7 @@ class RedisDb(BaseDb):
         metrics_table: Optional[str] = None,
         eval_table: Optional[str] = None,
         knowledge_table: Optional[str] = None,
+        culture_table: Optional[str] = None,
     ):
         """
         Interface for interacting with a Redis database.
@@ -64,6 +68,7 @@ class RedisDb(BaseDb):
             metrics_table (Optional[str]): Name of the table to store metrics
             eval_table (Optional[str]): Name of the table to store evaluation runs
             knowledge_table (Optional[str]): Name of the table to store knowledge documents
+            culture_table (Optional[str]): Name of the table to store cultural knowledge
 
         Raises:
             ValueError: If neither redis_client nor db_url is provided.
@@ -80,6 +85,7 @@ class RedisDb(BaseDb):
             metrics_table=metrics_table,
             eval_table=eval_table,
             knowledge_table=knowledge_table,
+            culture_table=culture_table,
         )
 
         self.db_prefix = db_prefix
@@ -111,6 +117,9 @@ class RedisDb(BaseDb):
         elif table_type == "knowledge":
             return self.knowledge_table_name
 
+        elif table_type == "culture":
+            return self.culture_table_name
+
         else:
             raise ValueError(f"Unknown table type: {table_type}")
 
@@ -1475,3 +1484,175 @@ class RedisDb(BaseDb):
         except Exception as e:
             log_error(f"Error updating eval run name {eval_run_id}: {e}")
             raise
+
+    # -- Cultural Knowledge methods --
+    def clear_cultural_knowledge(self) -> None:
+        """Delete all cultural knowledge from the database.
+
+        Raises:
+            Exception: If an error occurs during deletion.
+        """
+        try:
+            keys = get_all_keys_for_table(redis_client=self.redis_client, prefix=self.db_prefix, table_type="culture")
+
+            if keys:
+                self.redis_client.delete(*keys)
+
+        except Exception as e:
+            log_error(f"Exception deleting all cultural knowledge: {e}")
+            raise e
+
+    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:
+            if self._delete_record("culture", id, index_fields=["name", "agent_id", "team_id"]):
+                log_debug(f"Successfully deleted cultural knowledge id: {id}")
+            else:
+                log_debug(f"No cultural knowledge found with id: {id}")
+
+        except Exception as e:
+            log_error(f"Error deleting cultural knowledge: {e}")
+            raise e
+
+    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:
+            cultural_knowledge = self._get_record("culture", id)
+
+            if cultural_knowledge is None:
+                return None
+
+            if not deserialize:
+                return cultural_knowledge
+
+            return deserialize_cultural_knowledge_from_db(cultural_knowledge)
+
+        except Exception as e:
+            log_error(f"Error getting cultural knowledge: {e}")
+            raise e
+
+    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:
+            all_cultural_knowledge = self._get_all_records("culture")
+
+            # Apply filters
+            filtered_items = []
+            for item in all_cultural_knowledge:
+                if agent_id is not None and item.get("agent_id") != agent_id:
+                    continue
+                if team_id is not None and item.get("team_id") != team_id:
+                    continue
+                if name is not None and name.lower() not in item.get("name", "").lower():
+                    continue
+
+                filtered_items.append(item)
+
+            sorted_items = apply_sorting(records=filtered_items, sort_by=sort_by, sort_order=sort_order)
+            paginated_items = apply_pagination(records=sorted_items, limit=limit, page=page)
+
+            if not deserialize:
+                return paginated_items, len(filtered_items)
+
+            return [deserialize_cultural_knowledge_from_db(item) for item in paginated_items]
+
+        except Exception as e:
+            log_error(f"Error getting all cultural knowledge: {e}")
+            raise e
+
+    def upsert_cultural_knowledge(
+        self, cultural_knowledge: CulturalKnowledge, deserialize: Optional[bool] = True
+    ) -> Optional[Union[CulturalKnowledge, Dict[str, Any]]]:
+        """Upsert cultural knowledge in Redis.
+
+        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:
+            # Serialize content, categories, and notes into a dict for DB storage
+            content_dict = serialize_cultural_knowledge_for_db(cultural_knowledge)
+            item_id = cultural_knowledge.id or str(uuid4())
+
+            # Create the item dict with serialized content
+            data = {
+                "id": item_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,
+            }
+
+            success = self._store_record("culture", item_id, data, index_fields=["name", "agent_id", "team_id"])
+
+            if not success:
+                return None
+
+            if not deserialize:
+                return data
+
+            return deserialize_cultural_knowledge_from_db(data)
+
+        except Exception as e:
+            log_error(f"Error upserting cultural knowledge: {e}")
+            raise e

agno/db/redis/schemas.py

@@ -81,6 +81,20 @@ KNOWLEDGE_SCHEMA = {
 }
 
 
+CULTURAL_KNOWLEDGE_SCHEMA = {
+    "id": {"type": "string", "primary_key": True},
+    "name": {"type": "string"},
+    "summary": {"type": "string"},
+    "content": {"type": "json"},
+    "metadata": {"type": "json"},
+    "input": {"type": "string"},
+    "created_at": {"type": "integer"},
+    "updated_at": {"type": "integer"},
+    "agent_id": {"type": "string"},
+    "team_id": {"type": "string"},
+}
+
+
 def get_table_schema_definition(table_type: str) -> dict[str, Any]:
     """
     Get the expected schema definition for the given table.

agno/db/redis/utils.py

@@ -6,6 +6,7 @@ from datetime import date, datetime, timedelta, timezone
 from typing import Any, Dict, List, Optional
 from uuid import UUID
 
+from agno.db.schemas.culture import CulturalKnowledge
 from agno.utils.log import log_warning
 
 try:
@@ -286,3 +287,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_for_db(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 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 a dict 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_from_db(db_row: Dict[str, Any]) -> CulturalKnowledge:
+    """Deserialize a database row to a CulturalKnowledge object.
+
+    The database stores content as a 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 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/schemas/__init__.py

@@ -1,3 +1,4 @@
+from agno.db.schemas.culture import CulturalKnowledge
 from agno.db.schemas.memory import UserMemory
 
-__all__ = ["UserMemory"]
+__all__ = ["CulturalKnowledge", "UserMemory"]

agno/db/schemas/culture.py

@@ -0,0 +1,120 @@
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional, Union
+
+from typing_extensions import List
+
+
+@dataclass
+class CulturalKnowledge:
+    """Model for Cultural Knowledge
+
+    Notice: Culture is an experimental feature and is subject to change.
+    """
+
+    # The id of the cultural knowledge, auto-generated if not provided
+    id: Optional[str] = None
+    name: Optional[str] = None
+
+    content: Optional[str] = None
+    categories: Optional[List[str]] = None
+    notes: Optional[List[str]] = None
+
+    summary: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+    input: Optional[str] = None
+
+    created_at: Optional[int] = field(default=None)
+    updated_at: Optional[int] = field(default=None)
+
+    agent_id: Optional[str] = None
+    team_id: Optional[str] = None
+
+    def __post_init__(self):
+        if self.name is not None and not self.name.strip():
+            raise ValueError("name must be a non-empty string")
+        self.created_at = _now_epoch_s() if self.created_at is None else _to_epoch_s(self.created_at)
+        self.updated_at = self.created_at if self.updated_at is None else _to_epoch_s(self.updated_at)
+
+    def bump_updated_at(self) -> None:
+        """Bump updated_at to now (UTC)."""
+        self.updated_at = _now_epoch_s()
+
+    def preview(self) -> Dict[str, Any]:
+        """Return a preview of the cultural knowledge"""
+        _preview: Dict[str, Any] = {
+            "name": self.name,
+        }
+        if self.categories is not None:
+            _preview["categories"] = self.categories
+        if self.summary is not None:
+            _preview["summary"] = self.summary[:100] + "..." if len(self.summary) > 100 else self.summary
+        if self.content is not None:
+            _preview["content"] = self.content[:100] + "..." if len(self.content) > 100 else self.content
+        if self.notes is not None:
+            _preview["notes"] = [note[:100] + "..." if len(note) > 100 else note for note in self.notes]
+        return _preview
+
+    def to_dict(self) -> Dict[str, Any]:
+        _dict = {
+            "id": self.id,
+            "name": self.name,
+            "summary": self.summary,
+            "content": self.content,
+            "categories": self.categories,
+            "metadata": self.metadata,
+            "notes": self.notes,
+            "input": self.input,
+            "created_at": (_epoch_to_rfc3339_z(self.created_at) if self.created_at is not None else None),
+            "updated_at": (_epoch_to_rfc3339_z(self.updated_at) if self.updated_at is not None else None),
+            "agent_id": self.agent_id,
+            "team_id": self.team_id,
+        }
+        return {k: v for k, v in _dict.items() if v is not None}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "CulturalKnowledge":
+        d = dict(data)
+
+        # Preserve 0 and None explicitly; only process if key exists
+        if "created_at" in d and d["created_at"] is not None:
+            d["created_at"] = _to_epoch_s(d["created_at"])
+        if "updated_at" in d and d["updated_at"] is not None:
+            d["updated_at"] = _to_epoch_s(d["updated_at"])
+
+        return cls(**d)
+
+
+def _now_epoch_s() -> int:
+    return int(datetime.now(timezone.utc).timestamp())
+
+
+def _to_epoch_s(value: Union[int, float, str, datetime]) -> int:
+    """Normalize various datetime representations to epoch seconds (UTC)."""
+    if isinstance(value, (int, float)):
+        # assume value is already in seconds
+        return int(value)
+
+    if isinstance(value, datetime):
+        dt = value
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return int(dt.timestamp())
+
+    if isinstance(value, str):
+        s = value.strip()
+        if s.endswith("Z"):
+            s = s[:-1] + "+00:00"
+        try:
+            dt = datetime.fromisoformat(s)
+        except ValueError as e:
+            raise ValueError(f"Unsupported datetime string: {value!r}") from e
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return int(dt.timestamp())
+
+    raise TypeError(f"Unsupported datetime value: {type(value)}")
+
+
+def _epoch_to_rfc3339_z(ts: Union[int, float]) -> str:
+    return datetime.fromtimestamp(float(ts), tz=timezone.utc).isoformat().replace("+00:00", "Z")

agno/db/singlestore/schemas.py

@@ -92,6 +92,19 @@ METRICS_TABLE_SCHEMA = {
     "completed": {"type": Boolean, "nullable": False, "default": False},
 }
 
+CULTURAL_KNOWLEDGE_TABLE_SCHEMA = {
+    "id": {"type": lambda: String(128), "primary_key": True, "nullable": False},
+    "name": {"type": lambda: String(255), "nullable": False, "index": True},
+    "summary": {"type": Text, "nullable": True},
+    "content": {"type": JSON, "nullable": True},
+    "metadata": {"type": JSON, "nullable": True},
+    "input": {"type": Text, "nullable": True},
+    "created_at": {"type": BigInteger, "nullable": True},
+    "updated_at": {"type": BigInteger, "nullable": True},
+    "agent_id": {"type": lambda: String(128), "nullable": True},
+    "team_id": {"type": lambda: String(128), "nullable": True},
+}
+
 
 def get_table_schema_definition(table_type: str) -> dict[str, Any]:
     """
@@ -107,6 +120,7 @@ def get_table_schema_definition(table_type: str) -> dict[str, Any]:
         "metrics": METRICS_TABLE_SCHEMA,
         "memories": USER_MEMORY_TABLE_SCHEMA,
         "knowledge": KNOWLEDGE_TABLE_SCHEMA,
+        "culture": CULTURAL_KNOWLEDGE_TABLE_SCHEMA,
     }
     schema = schemas.get(table_type, {})