agno 2.0.1__py3-none-any.whl → 2.3.0__py3-none-any.whl

agno/os/routers/memory/memory.py

@@ -1,12 +1,12 @@
 import logging
 import math
-from typing import List, Optional
+from typing import List, Optional, Union, cast
 from uuid import uuid4
 
-from fastapi import Depends, HTTPException, Path, Query
+from fastapi import Depends, HTTPException, Path, Query, Request
 from fastapi.routing import APIRouter
 
-from agno.db.base import BaseDb
+from agno.db.base import AsyncBaseDb, BaseDb
 from agno.db.schemas import UserMemory
 from agno.os.auth import get_authentication_dependency
 from agno.os.routers.memory.schemas import (
@@ -31,7 +31,9 @@ from agno.os.utils import get_db
 logger = logging.getLogger(__name__)
 
 
-def get_memory_router(dbs: dict[str, BaseDb], settings: AgnoAPISettings = AgnoAPISettings(), **kwargs) -> APIRouter:
+def get_memory_router(
+    dbs: dict[str, list[Union[BaseDb, AsyncBaseDb]]], settings: AgnoAPISettings = AgnoAPISettings(), **kwargs
+) -> APIRouter:
     """Create memory router with comprehensive OpenAPI documentation for user memory management endpoints."""
     router = APIRouter(
         dependencies=[Depends(get_authentication_dependency(settings))],
@@ -47,7 +49,7 @@ def get_memory_router(dbs: dict[str, BaseDb], settings: AgnoAPISettings = AgnoAP
     return attach_routes(router=router, dbs=dbs)
 
 
-def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
+def attach_routes(router: APIRouter, dbs: dict[str, list[Union[BaseDb, AsyncBaseDb]]]) -> APIRouter:
     @router.post(
         "/memories",
         response_model=UserMemorySchema,
@@ -80,19 +82,42 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         },
     )
     async def create_memory(
+        request: Request,
         payload: UserMemoryCreateSchema,
         db_id: Optional[str] = Query(default=None, description="Database ID to use for memory storage"),
+        table: Optional[str] = Query(default=None, description="Table to use for memory storage"),
     ) -> UserMemorySchema:
-        db = get_db(dbs, db_id)
-        user_memory = db.upsert_user_memory(
-            memory=UserMemory(
-                memory_id=str(uuid4()),
-                memory=payload.memory,
-                topics=payload.topics or [],
-                user_id=payload.user_id,
-            ),
-            deserialize=False,
-        )
+        if hasattr(request.state, "user_id"):
+            user_id = request.state.user_id
+            payload.user_id = user_id
+
+        if payload.user_id is None:
+            raise HTTPException(status_code=400, detail="User ID is required")
+
+        db = await get_db(dbs, db_id, table)
+
+        if isinstance(db, AsyncBaseDb):
+            db = cast(AsyncBaseDb, db)
+            user_memory = await db.upsert_user_memory(
+                memory=UserMemory(
+                    memory_id=str(uuid4()),
+                    memory=payload.memory,
+                    topics=payload.topics or [],
+                    user_id=payload.user_id,
+                ),
+                deserialize=False,
+            )
+        else:
+            user_memory = db.upsert_user_memory(
+                memory=UserMemory(
+                    memory_id=str(uuid4()),
+                    memory=payload.memory,
+                    topics=payload.topics or [],
+                    user_id=payload.user_id,
+                ),
+                deserialize=False,
+            )
+
         if not user_memory:
             raise HTTPException(status_code=500, detail="Failed to create memory")
 
@@ -112,10 +137,16 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
     )
     async def delete_memory(
         memory_id: str = Path(description="Memory ID to delete"),
+        user_id: Optional[str] = Query(default=None, description="User ID to delete memory for"),
         db_id: Optional[str] = Query(default=None, description="Database ID to use for deletion"),
+        table: Optional[str] = Query(default=None, description="Table to use for deletion"),
     ) -> None:
-        db = get_db(dbs, db_id)
-        db.delete_user_memory(memory_id=memory_id)
+        db = await get_db(dbs, db_id, table)
+        if isinstance(db, AsyncBaseDb):
+            db = cast(AsyncBaseDb, db)
+            await db.delete_user_memory(memory_id=memory_id, user_id=user_id)
+        else:
+            db.delete_user_memory(memory_id=memory_id, user_id=user_id)
 
     @router.delete(
         "/memories",
@@ -135,9 +166,14 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
     async def delete_memories(
         request: DeleteMemoriesRequest,
         db_id: Optional[str] = Query(default=None, description="Database ID to use for deletion"),
+        table: Optional[str] = Query(default=None, description="Table to use for deletion"),
     ) -> None:
-        db = get_db(dbs, db_id)
-        db.delete_user_memories(memory_ids=request.memory_ids)
+        db = await get_db(dbs, db_id, table)
+        if isinstance(db, AsyncBaseDb):
+            db = cast(AsyncBaseDb, db)
+            await db.delete_user_memories(memory_ids=request.memory_ids, user_id=request.user_id)
+        else:
+            db.delete_user_memories(memory_ids=request.memory_ids, user_id=request.user_id)
 
     @router.get(
         "/memories",
@@ -173,6 +209,7 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         },
     )
     async def get_memories(
+        request: Request,
         user_id: Optional[str] = Query(default=None, description="Filter memories by user ID"),
         agent_id: Optional[str] = Query(default=None, description="Filter memories by agent ID"),
         team_id: Optional[str] = Query(default=None, description="Filter memories by team ID"),
@@ -183,22 +220,44 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         sort_by: Optional[str] = Query(default="updated_at", description="Field to sort memories by"),
         sort_order: Optional[SortOrder] = Query(default="desc", description="Sort order (asc or desc)"),
         db_id: Optional[str] = Query(default=None, description="Database ID to query memories from"),
+        table: Optional[str] = Query(default=None, description="The database table to use"),
     ) -> PaginatedResponse[UserMemorySchema]:
-        db = get_db(dbs, db_id)
-        user_memories, total_count = db.get_user_memories(
-            limit=limit,
-            page=page,
-            user_id=user_id,
-            agent_id=agent_id,
-            team_id=team_id,
-            topics=topics,
-            search_content=search_content,
-            sort_by=sort_by,
-            sort_order=sort_order,
-            deserialize=False,
-        )
+        db = await get_db(dbs, db_id, table)
+
+        if hasattr(request.state, "user_id"):
+            user_id = request.state.user_id
+
+        if isinstance(db, AsyncBaseDb):
+            db = cast(AsyncBaseDb, db)
+            user_memories, total_count = await db.get_user_memories(
+                limit=limit,
+                page=page,
+                user_id=user_id,
+                agent_id=agent_id,
+                team_id=team_id,
+                topics=topics,
+                search_content=search_content,
+                sort_by=sort_by,
+                sort_order=sort_order,
+                deserialize=False,
+            )
+        else:
+            user_memories, total_count = db.get_user_memories(  # type: ignore
+                limit=limit,
+                page=page,
+                user_id=user_id,
+                agent_id=agent_id,
+                team_id=team_id,
+                topics=topics,
+                search_content=search_content,
+                sort_by=sort_by,
+                sort_order=sort_order,
+                deserialize=False,
+            )
+
+        memories = [UserMemorySchema.from_dict(user_memory) for user_memory in user_memories]  # type: ignore
         return PaginatedResponse(
-            data=[UserMemorySchema.from_dict(user_memory) for user_memory in user_memories],  # type: ignore
+            data=[memory for memory in memories if memory is not None],
             meta=PaginationInfo(
                 page=page,
                 limit=limit,
@@ -235,11 +294,22 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         },
     )
     async def get_memory(
+        request: Request,
         memory_id: str = Path(description="Memory ID to retrieve"),
+        user_id: Optional[str] = Query(default=None, description="User ID to query memory for"),
         db_id: Optional[str] = Query(default=None, description="Database ID to query memory from"),
+        table: Optional[str] = Query(default=None, description="Table to query memory from"),
     ) -> UserMemorySchema:
-        db = get_db(dbs, db_id)
-        user_memory = db.get_user_memory(memory_id=memory_id, deserialize=False)
+        db = await get_db(dbs, db_id, table)
+
+        if hasattr(request.state, "user_id"):
+            user_id = request.state.user_id
+
+        if isinstance(db, AsyncBaseDb):
+            db = cast(AsyncBaseDb, db)
+            user_memory = await db.get_user_memory(memory_id=memory_id, user_id=user_id, deserialize=False)
+        else:
+            user_memory = db.get_user_memory(memory_id=memory_id, user_id=user_id, deserialize=False)
         if not user_memory:
             raise HTTPException(status_code=404, detail=f"Memory with ID {memory_id} not found")
 
@@ -278,9 +348,14 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
     )
     async def get_topics(
         db_id: Optional[str] = Query(default=None, description="Database ID to query topics from"),
+        table: Optional[str] = Query(default=None, description="Table to query topics from"),
     ) -> List[str]:
-        db = get_db(dbs, db_id)
-        return db.get_all_memory_topics()
+        db = await get_db(dbs, db_id, table)
+        if isinstance(db, AsyncBaseDb):
+            db = cast(AsyncBaseDb, db)
+            return await db.get_all_memory_topics()
+        else:
+            return db.get_all_memory_topics()
 
     @router.patch(
         "/memories/{memory_id}",
@@ -316,20 +391,42 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         },
     )
     async def update_memory(
+        request: Request,
         payload: UserMemoryCreateSchema,
         memory_id: str = Path(description="Memory ID to update"),
         db_id: Optional[str] = Query(default=None, description="Database ID to use for update"),
+        table: Optional[str] = Query(default=None, description="Table to use for update"),
     ) -> UserMemorySchema:
-        db = get_db(dbs, db_id)
-        user_memory = db.upsert_user_memory(
-            memory=UserMemory(
-                memory_id=memory_id,
-                memory=payload.memory,
-                topics=payload.topics or [],
-                user_id=payload.user_id,
-            ),
-            deserialize=False,
-        )
+        if hasattr(request.state, "user_id"):
+            user_id = request.state.user_id
+            payload.user_id = user_id
+
+        if payload.user_id is None:
+            raise HTTPException(status_code=400, detail="User ID is required")
+
+        db = await get_db(dbs, db_id, table)
+
+        if isinstance(db, AsyncBaseDb):
+            db = cast(AsyncBaseDb, db)
+            user_memory = await db.upsert_user_memory(
+                memory=UserMemory(
+                    memory_id=memory_id,
+                    memory=payload.memory,
+                    topics=payload.topics or [],
+                    user_id=payload.user_id,
+                ),
+                deserialize=False,
+            )
+        else:
+            user_memory = db.upsert_user_memory(
+                memory=UserMemory(
+                    memory_id=memory_id,
+                    memory=payload.memory,
+                    topics=payload.topics or [],
+                    user_id=payload.user_id,
+                ),
+                deserialize=False,
+            )
         if not user_memory:
             raise HTTPException(status_code=500, detail="Failed to update memory")
 
@@ -369,13 +466,21 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         limit: Optional[int] = Query(default=20, description="Number of user statistics to return per page"),
         page: Optional[int] = Query(default=1, description="Page number for pagination"),
         db_id: Optional[str] = Query(default=None, description="Database ID to query statistics from"),
+        table: Optional[str] = Query(default=None, description="Table to query statistics from"),
     ) -> PaginatedResponse[UserStatsSchema]:
-        db = get_db(dbs, db_id)
+        db = await get_db(dbs, db_id, table)
         try:
-            user_stats, total_count = db.get_user_memory_stats(
-                limit=limit,
-                page=page,
-            )
+            if isinstance(db, AsyncBaseDb):
+                db = cast(AsyncBaseDb, db)
+                user_stats, total_count = await db.get_user_memory_stats(
+                    limit=limit,
+                    page=page,
+                )
+            else:
+                user_stats, total_count = db.get_user_memory_stats(
+                    limit=limit,
+                    page=page,
+                )
             return PaginatedResponse(
                 data=[UserStatsSchema.from_dict(stats) for stats in user_stats],
                 meta=PaginationInfo(
@@ -396,7 +501,7 @@ def parse_topics(
     topics: Optional[List[str]] = Query(
         default=None,
         description="Comma-separated list of topics to filter by",
-        example=["preferences,technical,communication_style"],
+        examples=["preferences,technical,communication_style"],
     ),
 ) -> Optional[List[str]]:
     """Parse comma-separated topics into a list for filtering memories by topic."""

agno/os/routers/memory/schemas.py

@@ -1,26 +1,30 @@
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class DeleteMemoriesRequest(BaseModel):
-    memory_ids: List[str]
+    memory_ids: List[str] = Field(..., description="List of memory IDs to delete", min_length=1)
+    user_id: Optional[str] = Field(None, description="User ID to filter memories for deletion")
 
 
 class UserMemorySchema(BaseModel):
-    memory_id: str
-    memory: str
-    topics: Optional[List[str]]
+    memory_id: str = Field(..., description="Unique identifier for the memory")
+    memory: str = Field(..., description="Memory content text")
+    topics: Optional[List[str]] = Field(None, description="Topics or tags associated with the memory")
 
-    agent_id: Optional[str]
-    team_id: Optional[str]
-    user_id: Optional[str]
+    agent_id: Optional[str] = Field(None, description="Agent ID associated with this memory")
+    team_id: Optional[str] = Field(None, description="Team ID associated with this memory")
+    user_id: Optional[str] = Field(None, description="User ID who owns this memory")
 
-    updated_at: Optional[datetime]
+    updated_at: Optional[datetime] = Field(None, description="Timestamp when memory was last updated")
 
     @classmethod
-    def from_dict(cls, memory_dict: Dict[str, Any]) -> "UserMemorySchema":
+    def from_dict(cls, memory_dict: Dict[str, Any]) -> Optional["UserMemorySchema"]:
+        if memory_dict["memory"] == "":
+            return None
+
         return cls(
             memory_id=memory_dict["memory_id"],
             user_id=str(memory_dict["user_id"]),
@@ -35,17 +39,17 @@ class UserMemorySchema(BaseModel):
 class UserMemoryCreateSchema(BaseModel):
     """Define the payload expected for creating a new user memory"""
 
-    memory: str
-    user_id: str
-    topics: Optional[List[str]] = None
+    memory: str = Field(..., description="Memory content text", min_length=1, max_length=5000)
+    user_id: Optional[str] = Field(None, description="User ID who owns this memory")
+    topics: Optional[List[str]] = Field(None, description="Topics or tags to categorize the memory")
 
 
 class UserStatsSchema(BaseModel):
     """Schema for user memory statistics"""
 
-    user_id: str
-    total_memories: int
-    last_memory_updated_at: Optional[datetime] = None
+    user_id: str = Field(..., description="User ID")
+    total_memories: int = Field(..., description="Total number of memories for this user", ge=0)
+    last_memory_updated_at: Optional[datetime] = Field(None, description="Timestamp of the most recent memory update")
 
     @classmethod
     def from_dict(cls, user_stats_dict: Dict[str, Any]) -> "UserStatsSchema":

agno/os/routers/metrics/metrics.py

@@ -1,11 +1,11 @@
 import logging
 from datetime import date, datetime, timezone
-from typing import List, Optional
+from typing import List, Optional, Union, cast
 
 from fastapi import Depends, HTTPException, Query
 from fastapi.routing import APIRouter
 
-from agno.db.base import BaseDb
+from agno.db.base import AsyncBaseDb, BaseDb
 from agno.os.auth import get_authentication_dependency
 from agno.os.routers.metrics.schemas import DayAggregatedMetrics, MetricsResponse
 from agno.os.schema import (
@@ -21,7 +21,9 @@ from agno.os.utils import get_db
 logger = logging.getLogger(__name__)
 
 
-def get_metrics_router(dbs: dict[str, BaseDb], settings: AgnoAPISettings = AgnoAPISettings(), **kwargs) -> APIRouter:
+def get_metrics_router(
+    dbs: dict[str, list[Union[BaseDb, AsyncBaseDb]]], settings: AgnoAPISettings = AgnoAPISettings(), **kwargs
+) -> APIRouter:
     """Create metrics router with comprehensive OpenAPI documentation for system metrics and analytics endpoints."""
     router = APIRouter(
         dependencies=[Depends(get_authentication_dependency(settings))],
@@ -37,7 +39,7 @@ def get_metrics_router(dbs: dict[str, BaseDb], settings: AgnoAPISettings = AgnoA
     return attach_routes(router=router, dbs=dbs)
 
 
-def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
+def attach_routes(router: APIRouter, dbs: dict[str, list[Union[BaseDb, AsyncBaseDb]]]) -> APIRouter:
     @router.get(
         "/metrics",
         response_model=MetricsResponse,
@@ -97,10 +99,15 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
             default=None, description="Ending date for metrics range (YYYY-MM-DD format)"
         ),
         db_id: Optional[str] = Query(default=None, description="Database ID to query metrics from"),
+        table: Optional[str] = Query(default=None, description="The database table to use"),
     ) -> MetricsResponse:
         try:
-            db = get_db(dbs, db_id)
-            metrics, latest_updated_at = db.get_metrics(starting_date=starting_date, ending_date=ending_date)
+            db = await get_db(dbs, db_id, table)
+            if isinstance(db, AsyncBaseDb):
+                db = cast(AsyncBaseDb, db)
+                metrics, latest_updated_at = await db.get_metrics(starting_date=starting_date, ending_date=ending_date)
+            else:
+                metrics, latest_updated_at = db.get_metrics(starting_date=starting_date, ending_date=ending_date)
 
             return MetricsResponse(
                 metrics=[DayAggregatedMetrics.from_dict(metric) for metric in metrics],
@@ -163,10 +170,15 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
     )
     async def calculate_metrics(
         db_id: Optional[str] = Query(default=None, description="Database ID to use for metrics calculation"),
+        table: Optional[str] = Query(default=None, description="Table to use for metrics calculation"),
     ) -> List[DayAggregatedMetrics]:
         try:
-            db = get_db(dbs, db_id)
-            result = db.calculate_metrics()
+            db = await get_db(dbs, db_id, table)
+            if isinstance(db, AsyncBaseDb):
+                db = cast(AsyncBaseDb, db)
+                result = await db.calculate_metrics()
+            else:
+                result = db.calculate_metrics()
             if result is None:
                 return []
 

agno/os/routers/metrics/schemas.py

@@ -1,27 +1,27 @@
 from datetime import datetime
 from typing import Any, Dict, List, Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class DayAggregatedMetrics(BaseModel):
     """Aggregated metrics for a given day"""
 
-    id: str
+    id: str = Field(..., description="Unique identifier for the metrics record")
 
-    agent_runs_count: int
-    agent_sessions_count: int
-    team_runs_count: int
-    team_sessions_count: int
-    workflow_runs_count: int
-    workflow_sessions_count: int
-    users_count: int
-    token_metrics: Dict[str, Any]
-    model_metrics: List[Dict[str, Any]]
+    agent_runs_count: int = Field(..., description="Total number of agent runs", ge=0)
+    agent_sessions_count: int = Field(..., description="Total number of agent sessions", ge=0)
+    team_runs_count: int = Field(..., description="Total number of team runs", ge=0)
+    team_sessions_count: int = Field(..., description="Total number of team sessions", ge=0)
+    workflow_runs_count: int = Field(..., description="Total number of workflow runs", ge=0)
+    workflow_sessions_count: int = Field(..., description="Total number of workflow sessions", ge=0)
+    users_count: int = Field(..., description="Total number of unique users", ge=0)
+    token_metrics: Dict[str, Any] = Field(..., description="Token usage metrics (input, output, cached, etc.)")
+    model_metrics: List[Dict[str, Any]] = Field(..., description="Metrics grouped by model (model_id, provider, count)")
 
-    date: datetime
-    created_at: int
-    updated_at: int
+    date: datetime = Field(..., description="Date for which these metrics are aggregated")
+    created_at: int = Field(..., description="Unix timestamp when metrics were created", ge=0)
+    updated_at: int = Field(..., description="Unix timestamp when metrics were last updated", ge=0)
 
     @classmethod
     def from_dict(cls, metrics_dict: Dict[str, Any]) -> "DayAggregatedMetrics":
@@ -43,5 +43,5 @@ class DayAggregatedMetrics(BaseModel):
 
 
 class MetricsResponse(BaseModel):
-    metrics: List[DayAggregatedMetrics]
-    updated_at: Optional[datetime]
+    metrics: List[DayAggregatedMetrics] = Field(..., description="List of daily aggregated metrics")
+    updated_at: Optional[datetime] = Field(None, description="Timestamp of the most recent metrics update")