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

agno/culture/manager.py

@@ -78,8 +78,6 @@ class CultureManager:
         self.delete_knowledge = delete_knowledge
         self.clear_knowledge = clear_knowledge
         self.debug_mode = debug_mode
-        self._tools_for_model: Optional[List[Dict[str, Any]]] = None
-        self._functions_for_model: Optional[Dict[str, Function]] = None
 
     def get_model(self) -> Model:
         if self.model is None:
@@ -316,23 +314,27 @@ class CultureManager:
         return response
 
     # -*- Utility Functions -*-
-    def _determine_tools_for_model(self, tools: List[Callable]) -> None:
+    def _determine_tools_for_model(self, tools: List[Callable]) -> List[Union[Function, dict]]:
         # Have to reset each time, because of different user IDs
-        self._tools_for_model = []
-        self._functions_for_model = {}
+
+        _function_names = []
+        _functions: List[Union[Function, dict]] = []
 
         for tool in tools:
             try:
                 function_name = tool.__name__
-                if function_name not in self._functions_for_model:
-                    func = Function.from_callable(tool, strict=True)  # type: ignore
-                    func.strict = True
-                    self._functions_for_model[func.name] = func
-                    self._tools_for_model.append({"type": "function", "function": func.to_dict()})
-                    log_debug(f"Added function {func.name}")
+                if function_name in _function_names:
+                    continue
+                _function_names.append(function_name)
+                func = Function.from_callable(tool, strict=True)  # type: ignore
+                func.strict = True
+                _functions.append(func)
+                log_debug(f"Added function {func.name}")
             except Exception as e:
                 log_warning(f"Could not add function {tool}: {e}")
 
+        return _functions
+
     def get_system_message(
         self,
         existing_knowledge: Optional[List[Dict[str, Any]]] = None,
@@ -460,7 +462,7 @@ class CultureManager:
 
         model_copy = deepcopy(self.model)
         # Update the Model (set defaults, add logit etc.)
-        self._determine_tools_for_model(
+        _tools = self._determine_tools_for_model(
             self._get_db_tools(
                 db,
                 enable_add_knowledge=add_knowledge,
@@ -485,8 +487,7 @@ class CultureManager:
         # Generate a response from the Model (includes running function calls)
         response = model_copy.response(
             messages=messages_for_model,
-            tools=self._tools_for_model,
-            functions=self._functions_for_model,
+            tools=_tools,
         )
 
         if response.tool_calls is not None and len(response.tool_calls) > 0:
@@ -513,7 +514,7 @@ class CultureManager:
         model_copy = deepcopy(self.model)
         db = cast(AsyncBaseDb, db)
 
-        self._determine_tools_for_model(
+        _tools = self._determine_tools_for_model(
             await self._aget_db_tools(
                 db,
                 enable_update_knowledge=update_knowledge,
@@ -535,8 +536,7 @@ class CultureManager:
         # Generate a response from the Model (includes running function calls)
         response = await model_copy.aresponse(
             messages=messages_for_model,
-            tools=self._tools_for_model,
-            functions=self._functions_for_model,
+            tools=_tools,
         )
 
         if response.tool_calls is not None and len(response.tool_calls) > 0:
@@ -564,7 +564,7 @@ class CultureManager:
 
         model_copy = deepcopy(self.model)
         # Update the Model (set defaults, add logit etc.)
-        self._determine_tools_for_model(
+        _tools = self._determine_tools_for_model(
             self._get_db_tools(
                 db,
                 enable_delete_knowledge=delete_knowledge,
@@ -590,8 +590,7 @@ class CultureManager:
         # Generate a response from the Model (includes running function calls)
         response = model_copy.response(
             messages=messages_for_model,
-            tools=self._tools_for_model,
-            functions=self._functions_for_model,
+            tools=_tools,
         )
 
         if response.tool_calls is not None and len(response.tool_calls) > 0:
@@ -620,7 +619,7 @@ class CultureManager:
         model_copy = deepcopy(self.model)
         # Update the Model (set defaults, add logit etc.)
         if isinstance(db, AsyncBaseDb):
-            self._determine_tools_for_model(
+            _tools = self._determine_tools_for_model(
                 await self._aget_db_tools(
                     db,
                     enable_delete_knowledge=delete_knowledge,
@@ -630,7 +629,7 @@ class CultureManager:
                 ),
             )
         else:
-            self._determine_tools_for_model(
+            _tools = self._determine_tools_for_model(
                 self._get_db_tools(
                     db,
                     enable_delete_knowledge=delete_knowledge,
@@ -656,8 +655,7 @@ class CultureManager:
         # Generate a response from the Model (includes running function calls)
         response = await model_copy.aresponse(
             messages=messages_for_model,
-            tools=self._tools_for_model,
-            functions=self._functions_for_model,
+            tools=_tools,
         )
 
         if response.tool_calls is not None and len(response.tool_calls) > 0:

agno/db/async_postgres/__init__.py

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

agno/db/dynamo/dynamo.py

@@ -277,8 +277,6 @@ class DynamoDb(BaseDb):
 
             session = deserialize_from_dynamodb_item(item)
 
-            if session.get("session_type") != session_type.value:
-                return None
             if user_id and session.get("user_id") != user_id:
                 return None
 

agno/db/firestore/firestore.py

@@ -280,8 +280,6 @@ class FirestoreDb(BaseDb):
 
             if user_id is not None:
                 query = query.where(filter=FieldFilter("user_id", "==", user_id))
-            if session_type is not None:
-                query = query.where(filter=FieldFilter("session_type", "==", session_type.value))
 
             docs = query.stream()
             result = None

agno/db/gcs_json/gcs_json_db.py

@@ -220,10 +220,6 @@ class GcsJsonDb(BaseDb):
                     if user_id is not None and session_data.get("user_id") != user_id:
                         continue
 
-                    session_type_value = session_type.value if isinstance(session_type, SessionType) else session_type
-                    if session_data.get("session_type") != session_type_value:
-                        continue
-
                     if not deserialize:
                         return session_data
 

agno/db/gcs_json/utils.py

@@ -5,34 +5,10 @@ from datetime import date, datetime, timedelta, timezone
 from typing import Any, Dict, List, Optional
 from uuid import uuid4
 
-from agno.db.base import SessionType
 from agno.db.schemas.culture import CulturalKnowledge
-from agno.run.agent import RunOutput
-from agno.run.team import TeamRunOutput
-from agno.session.summary import SessionSummary
 from agno.utils.log import log_debug
 
 
-def hydrate_session(session: dict) -> dict:
-    """Convert nested dictionaries to their corresponding object types.
-
-    Args:
-        session (dict): The session dictionary to hydrate.
-
-    Returns:
-        dict: The hydrated session dictionary.
-    """
-    if session.get("summary") is not None:
-        session["summary"] = SessionSummary.from_dict(session["summary"])
-    if session.get("runs") is not None:
-        if session["session_type"] == SessionType.AGENT:
-            session["runs"] = [RunOutput.from_dict(run) for run in session["runs"]]
-        elif session["session_type"] == SessionType.TEAM:
-            session["runs"] = [TeamRunOutput.from_dict(run) for run in session["runs"]]
-
-    return session
-
-
 def apply_sorting(
     data: List[Dict[str, Any]], sort_by: Optional[str] = None, sort_order: Optional[str] = None
 ) -> List[Dict[str, Any]]:

agno/db/in_memory/in_memory_db.py

@@ -108,9 +108,6 @@ class InMemoryDb(BaseDb):
                 if session_data.get("session_id") == session_id:
                     if user_id is not None and session_data.get("user_id") != user_id:
                         continue
-                    session_type_value = session_type.value if isinstance(session_type, SessionType) else session_type
-                    if session_data.get("session_type") != session_type_value:
-                        continue
 
                     session_data_copy = deepcopy(session_data)
 

agno/db/json/json_db.py

@@ -13,7 +13,6 @@ from agno.db.json.utils import (
     deserialize_cultural_knowledge_from_db,
     fetch_all_sessions_data,
     get_dates_to_calculate_metrics_for,
-    hydrate_session,
     serialize_cultural_knowledge_for_db,
 )
 from agno.db.schemas.culture import CulturalKnowledge
@@ -202,21 +201,16 @@ class JsonDb(BaseDb):
                 if session_data.get("session_id") == session_id:
                     if user_id is not None and session_data.get("user_id") != user_id:
                         continue
-                    session_type_value = session_type.value if isinstance(session_type, SessionType) else session_type
-                    if session_data.get("session_type") != session_type_value:
-                        continue
-
-                    session = hydrate_session(session_data)
 
                     if not deserialize:
-                        return session
+                        return session_data
 
                     if session_type == SessionType.AGENT:
-                        return AgentSession.from_dict(session)
+                        return AgentSession.from_dict(session_data)
                     elif session_type == SessionType.TEAM:
-                        return TeamSession.from_dict(session)
+                        return TeamSession.from_dict(session_data)
                     elif session_type == SessionType.WORKFLOW:
-                        return WorkflowSession.from_dict(session)
+                        return WorkflowSession.from_dict(session_data)
                     else:
                         raise ValueError(f"Invalid session type: {session_type}")
 

agno/db/json/utils.py

@@ -5,34 +5,10 @@ from datetime import date, datetime, timedelta, timezone
 from typing import Any, Dict, List, Optional
 from uuid import uuid4
 
-from agno.db.base import SessionType
 from agno.db.schemas.culture import CulturalKnowledge
-from agno.run.agent import RunOutput
-from agno.run.team import TeamRunOutput
-from agno.session.summary import SessionSummary
 from agno.utils.log import log_debug
 
 
-def hydrate_session(session: dict) -> dict:
-    """Convert nested dictionaries to their corresponding object types.
-
-    Args:
-        session (dict): The session dictionary to hydrate.
-
-    Returns:
-        dict: The hydrated session dictionary.
-    """
-    if session.get("summary") is not None:
-        session["summary"] = SessionSummary.from_dict(session["summary"])
-    if session.get("runs") is not None:
-        if session["session_type"] == SessionType.AGENT:
-            session["runs"] = [RunOutput.from_dict(run) for run in session["runs"]]
-        elif session["session_type"] == SessionType.TEAM:
-            session["runs"] = [TeamRunOutput.from_dict(run) for run in session["runs"]]
-
-    return session
-
-
 def apply_sorting(
     data: List[Dict[str, Any]], sort_by: Optional[str] = None, sort_order: Optional[str] = None
 ) -> List[Dict[str, Any]]:

agno/db/mongo/mongo.py

@@ -291,8 +291,6 @@ class MongoDb(BaseDb):
             query = {"session_id": session_id}
             if user_id is not None:
                 query["user_id"] = user_id
-            if session_type is not None:
-                query["session_type"] = session_type
 
             result = collection.find_one(query)
             if result is None:

agno/db/mysql/mysql.py

@@ -387,9 +387,6 @@ class MySQLDb(BaseDb):
 
                 if user_id is not None:
                     stmt = stmt.where(table.c.user_id == user_id)
-                if session_type is not None:
-                    session_type_value = session_type.value if isinstance(session_type, SessionType) else session_type
-                    stmt = stmt.where(table.c.session_type == session_type_value)
                 result = sess.execute(stmt).fetchone()
                 if result is None:
                     return None

agno/db/postgres/__init__.py

@@ -1,4 +1,4 @@
-from agno.db.async_postgres import AsyncPostgresDb
+from agno.db.postgres.async_postgres import AsyncPostgresDb
 from agno.db.postgres.postgres import PostgresDb
 
 __all__ = ["PostgresDb", "AsyncPostgresDb"]

agno/db/{async_postgres → postgres}/async_postgres.py

@@ -3,20 +3,20 @@ from datetime import date, datetime, timedelta, timezone
 from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
 from uuid import uuid4
 
-from agno.db.async_postgres.schemas import get_table_schema_definition
-from agno.db.async_postgres.utils import (
+from agno.db.base import AsyncBaseDb, SessionType
+from agno.db.postgres.schemas import get_table_schema_definition
+from agno.db.postgres.utils import (
+    abulk_upsert_metrics,
+    acreate_schema,
+    ais_table_available,
+    ais_valid_table,
     apply_sorting,
-    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
@@ -148,7 +148,7 @@ class AsyncPostgresDb(AsyncBaseDb):
                 table.append_constraint(Index(idx_name, idx_col))
 
             async with self.async_session_factory() as sess, sess.begin():
-                await create_schema(session=sess, db_schema=db_schema)
+                await acreate_schema(session=sess, db_schema=db_schema)
 
             # Create table
             async with self.db_engine.begin() as conn:
@@ -241,12 +241,12 @@ class AsyncPostgresDb(AsyncBaseDb):
         """
 
         async with self.async_session_factory() as sess, sess.begin():
-            table_is_available = await is_table_available(session=sess, table_name=table_name, db_schema=db_schema)
+            table_is_available = await ais_table_available(session=sess, table_name=table_name, db_schema=db_schema)
 
         if not table_is_available:
             return await self._create_table(table_name=table_name, table_type=table_type, db_schema=db_schema)
 
-        if not await is_valid_table(
+        if not await ais_valid_table(
             db_engine=self.db_engine,
             table_name=table_name,
             table_type=table_type,
@@ -288,7 +288,7 @@ class AsyncPostgresDb(AsyncBaseDb):
                 delete_stmt = table.delete().where(table.c.session_id == session_id)
                 result = await sess.execute(delete_stmt)
 
-                if result.rowcount == 0:
+                if result.rowcount == 0:  # type: ignore
                     log_debug(f"No session found to delete with session_id: {session_id} in table {table.name}")
                     return False
 
@@ -317,7 +317,7 @@ class AsyncPostgresDb(AsyncBaseDb):
                 delete_stmt = table.delete().where(table.c.session_id.in_(session_ids))
                 result = await sess.execute(delete_stmt)
 
-            log_debug(f"Successfully deleted {result.rowcount} sessions")
+            log_debug(f"Successfully deleted {result.rowcount} sessions")  # type: ignore
 
         except Exception as e:
             log_error(f"Error deleting sessions: {e}")
@@ -354,9 +354,6 @@ class AsyncPostgresDb(AsyncBaseDb):
 
                 if user_id is not None:
                     stmt = stmt.where(table.c.user_id == user_id)
-                if session_type is not None:
-                    session_type_value = session_type.value if isinstance(session_type, SessionType) else session_type
-                    stmt = stmt.where(table.c.session_type == session_type_value)
                 result = await sess.execute(stmt)
                 row = result.fetchone()
                 if row is None:
@@ -712,7 +709,7 @@ class AsyncPostgresDb(AsyncBaseDb):
                 delete_stmt = table.delete().where(table.c.memory_id == memory_id)
                 result = await sess.execute(delete_stmt)
 
-                success = result.rowcount > 0
+                success = result.rowcount > 0  # type: ignore
                 if success:
                     log_debug(f"Successfully deleted user memory id: {memory_id}")
                 else:
@@ -737,10 +734,10 @@ class AsyncPostgresDb(AsyncBaseDb):
                 delete_stmt = table.delete().where(table.c.memory_id.in_(memory_ids))
                 result = await sess.execute(delete_stmt)
 
-                if result.rowcount == 0:
+                if result.rowcount == 0:  # type: ignore
                     log_debug(f"No user memories found with ids: {memory_ids}")
                 else:
-                    log_debug(f"Successfully deleted {result.rowcount} user memories")
+                    log_debug(f"Successfully deleted {result.rowcount} user memories")  # type: ignore
 
         except Exception as e:
             log_error(f"Error deleting user memories: {e}")
@@ -1387,7 +1384,7 @@ class AsyncPostgresDb(AsyncBaseDb):
 
             if metrics_records:
                 async with self.async_session_factory() as sess, sess.begin():
-                    results = await bulk_upsert_metrics(session=sess, table=table, metrics_records=metrics_records)
+                    results = await abulk_upsert_metrics(session=sess, table=table, metrics_records=metrics_records)
 
             log_debug("Updated metrics calculations")
 
@@ -1649,7 +1646,7 @@ class AsyncPostgresDb(AsyncBaseDb):
                 stmt = table.delete().where(table.c.run_id == eval_run_id)
                 result = await sess.execute(stmt)
 
-                if result.rowcount == 0:
+                if result.rowcount == 0:  # type: ignore
                     log_warning(f"No eval run found with ID: {eval_run_id}")
                 else:
                     log_debug(f"Deleted eval run with ID: {eval_run_id}")
@@ -1670,10 +1667,10 @@ class AsyncPostgresDb(AsyncBaseDb):
                 stmt = table.delete().where(table.c.run_id.in_(eval_run_ids))
                 result = await sess.execute(stmt)
 
-                if result.rowcount == 0:
+                if result.rowcount == 0:  # type: ignore
                     log_warning(f"No eval runs found with IDs: {eval_run_ids}")
                 else:
-                    log_debug(f"Deleted {result.rowcount} eval runs")
+                    log_debug(f"Deleted {result.rowcount} eval runs")  # type: ignore
 
         except Exception as e:
             log_error(f"Error deleting eval runs {eval_run_ids}: {e}")

agno/db/postgres/postgres.py

@@ -10,12 +10,12 @@ from agno.db.postgres.utils import (
     bulk_upsert_metrics,
     calculate_date_metrics,
     create_schema,
-    deserialize_cultural_knowledge_from_db,
+    deserialize_cultural_knowledge,
     fetch_all_sessions_data,
     get_dates_to_calculate_metrics_for,
     is_table_available,
     is_valid_table,
-    serialize_cultural_knowledge_for_db,
+    serialize_cultural_knowledge,
 )
 from agno.db.schemas.culture import CulturalKnowledge
 from agno.db.schemas.evals import EvalFilterType, EvalRunRecord, EvalType
@@ -383,9 +383,6 @@ class PostgresDb(BaseDb):
 
                 if user_id is not None:
                     stmt = stmt.where(table.c.user_id == user_id)
-                if session_type is not None:
-                    session_type_value = session_type.value if isinstance(session_type, SessionType) else session_type
-                    stmt = stmt.where(table.c.session_type == session_type_value)
                 result = sess.execute(stmt).fetchone()
                 if result is None:
                     return None
@@ -2030,7 +2027,7 @@ class PostgresDb(BaseDb):
                 if not db_row or not deserialize:
                     return db_row
 
-            return deserialize_cultural_knowledge_from_db(db_row)
+            return deserialize_cultural_knowledge(db_row)
 
         except Exception as e:
             log_error(f"Exception reading from cultural knowledge table: {e}")
@@ -2104,7 +2101,7 @@ class PostgresDb(BaseDb):
                 if not deserialize:
                     return db_rows, total_count
 
-            return [deserialize_cultural_knowledge_from_db(row) for row in db_rows]
+            return [deserialize_cultural_knowledge(row) for row in db_rows]
 
         except Exception as e:
             log_error(f"Error reading from cultural knowledge table: {e}")
@@ -2134,7 +2131,7 @@ class PostgresDb(BaseDb):
                 cultural_knowledge.id = str(uuid4())
 
             # Serialize content, categories, and notes into a JSON dict for DB storage
-            content_dict = serialize_cultural_knowledge_for_db(cultural_knowledge)
+            content_dict = serialize_cultural_knowledge(cultural_knowledge)
 
             with self.Session() as sess, sess.begin():
                 stmt = postgresql.insert(table).values(
@@ -2149,7 +2146,7 @@ class PostgresDb(BaseDb):
                     agent_id=cultural_knowledge.agent_id,
                     team_id=cultural_knowledge.team_id,
                 )
-                stmt = stmt.on_conflict_do_update(
+                stmt = stmt.on_conflict_do_update(  # type: ignore
                     index_elements=["id"],
                     set_=dict(
                         name=cultural_knowledge.name,
@@ -2173,7 +2170,7 @@ class PostgresDb(BaseDb):
             if not db_row or not deserialize:
                 return db_row
 
-            return deserialize_cultural_knowledge_from_db(db_row)
+            return deserialize_cultural_knowledge(db_row)
 
         except Exception as e:
             log_error(f"Error upserting cultural knowledge: {e}")

agno/db/postgres/utils.py

@@ -6,6 +6,7 @@ from typing import Any, Dict, List, Optional
 from uuid import uuid4
 
 from sqlalchemy import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
 
 from agno.db.postgres.schemas import get_table_schema_definition
 from agno.db.schemas.culture import CulturalKnowledge
@@ -63,6 +64,20 @@ def create_schema(session: Session, db_schema: str) -> None:
         log_warning(f"Could not create schema {db_schema}: {e}")
 
 
+async def acreate_schema(session: AsyncSession, db_schema: str) -> None:
+    """Create the database schema if it doesn't exist.
+
+    Args:
+        session: The SQLAlchemy session to use
+        db_schema (str): The definition of the database schema to create
+    """
+    try:
+        log_debug(f"Creating schema if not exists: {db_schema}")
+        await session.execute(text(f"CREATE SCHEMA IF NOT EXISTS {db_schema};"))
+    except Exception as e:
+        log_warning(f"Could not create schema {db_schema}: {e}")
+
+
 def is_table_available(session: Session, table_name: str, db_schema: str) -> bool:
     """
     Check if a table with the given name exists in the given schema.
@@ -82,6 +97,24 @@ def is_table_available(session: Session, table_name: str, db_schema: str) -> boo
         return False
 
 
+async def ais_table_available(session: AsyncSession, table_name: str, db_schema: str) -> bool:
+    """
+    Check if a table with the given name exists in the given schema.
+
+    Returns:
+        bool: True if the table exists, False otherwise.
+    """
+    try:
+        exists_query = text(
+            "SELECT 1 FROM information_schema.tables WHERE table_schema = :schema AND table_name = :table"
+        )
+        exists = (await session.execute(exists_query, {"schema": db_schema, "table": table_name})).scalar() is not None
+        return exists
+    except Exception as e:
+        log_error(f"Error checking if table exists: {e}")
+        return False
+
+
 def is_valid_table(db_engine: Engine, table_name: str, table_type: str, db_schema: str) -> bool:
     """
     Check if the existing table has the expected column names.
@@ -114,6 +147,44 @@ def is_valid_table(db_engine: Engine, table_name: str, table_type: str, db_schem
         return False
 
 
+async def ais_valid_table(db_engine: AsyncEngine, table_name: str, table_type: str, db_schema: str) -> bool:
+    """
+    Check if the existing table has the expected column names.
+
+    Args:
+        table_name (str): Name of the table to validate
+        schema (str): Database schema name
+
+    Returns:
+        bool: True if table has all expected columns, False otherwise
+    """
+    try:
+        expected_table_schema = get_table_schema_definition(table_type)
+        expected_columns = {col_name for col_name in expected_table_schema.keys() if not col_name.startswith("_")}
+
+        # Get existing columns from the async engine
+        async with db_engine.connect() as conn:
+            existing_columns = await conn.run_sync(_get_table_columns, table_name, db_schema)
+
+        # Check if all expected columns exist
+        missing_columns = expected_columns - existing_columns
+        if missing_columns:
+            log_warning(f"Missing columns {missing_columns} in table {db_schema}.{table_name}")
+            return False
+
+        return True
+    except Exception as e:
+        log_error(f"Error validating table schema for {db_schema}.{table_name}: {e}")
+        return False
+
+
+def _get_table_columns(conn, table_name: str, db_schema: str) -> set[str]:
+    """Helper function to get table columns using sync inspector."""
+    inspector = inspect(conn)
+    columns_info = inspector.get_columns(table_name, schema=db_schema)
+    return {col["name"] for col in columns_info}
+
+
 # -- Metrics util methods --
 def bulk_upsert_metrics(session: Session, table: Table, metrics_records: list[dict]) -> list[dict]:
     """Bulk upsert metrics into the database.
@@ -148,6 +219,39 @@ def bulk_upsert_metrics(session: Session, table: Table, metrics_records: list[di
     return results  # type: ignore
 
 
+async def abulk_upsert_metrics(session: AsyncSession, table: Table, metrics_records: list[dict]) -> list[dict]:
+    """Bulk upsert metrics into the database.
+
+    Args:
+        table (Table): The table to upsert into.
+        metrics_records (list[dict]): The metrics records to upsert.
+
+    Returns:
+        list[dict]: The upserted metrics records.
+    """
+    if not metrics_records:
+        return []
+
+    results = []
+    stmt = postgresql.insert(table)
+
+    # Columns to update in case of conflict
+    update_columns = {
+        col.name: stmt.excluded[col.name]
+        for col in table.columns
+        if col.name not in ["id", "date", "created_at", "aggregation_period"]
+    }
+
+    stmt = stmt.on_conflict_do_update(index_elements=["date", "aggregation_period"], set_=update_columns).returning(  # type: ignore
+        table
+    )
+    result = await session.execute(stmt, metrics_records)
+    results = [row._mapping for row in result.fetchall()]
+    await session.commit()
+
+    return results  # type: ignore
+
+
 def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     """Calculate metrics for the given single date.
 
@@ -282,7 +386,7 @@ def get_dates_to_calculate_metrics_for(starting_date: date) -> list[date]:
 
 
 # -- Cultural Knowledge util methods --
-def serialize_cultural_knowledge_for_db(cultural_knowledge: CulturalKnowledge) -> Dict[str, Any]:
+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
@@ -305,7 +409,7 @@ def serialize_cultural_knowledge_for_db(cultural_knowledge: CulturalKnowledge) -
     return content_dict if content_dict else {}
 
 
-def deserialize_cultural_knowledge_from_db(db_row: Dict[str, Any]) -> CulturalKnowledge:
+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.