agno 2.0.0rc1__py3-none-any.whl → 2.0.0rc2__py3-none-any.whl

agno/os/routers/memory/memory.py

@@ -15,7 +15,16 @@ from agno.os.routers.memory.schemas import (
     UserMemorySchema,
     UserStatsSchema,
 )
-from agno.os.schema import PaginatedResponse, PaginationInfo, SortOrder
+from agno.os.schema import (
+    BadRequestResponse,
+    InternalServerErrorResponse,
+    NotFoundResponse,
+    PaginatedResponse,
+    PaginationInfo,
+    SortOrder,
+    UnauthenticatedResponse,
+    ValidationErrorResponse,
+)
 from agno.os.settings import AgnoAPISettings
 from agno.os.utils import get_db
 
@@ -23,15 +32,56 @@ logger = logging.getLogger(__name__)
 
 
 def get_memory_router(dbs: dict[str, BaseDb], settings: AgnoAPISettings = AgnoAPISettings(), **kwargs) -> APIRouter:
-    router = APIRouter(dependencies=[Depends(get_authentication_dependency(settings))], tags=["Memory"])
+    """Create memory router with comprehensive OpenAPI documentation for user memory management endpoints."""
+    router = APIRouter(
+        dependencies=[Depends(get_authentication_dependency(settings))],
+        tags=["Memory"],
+        responses={
+            400: {"description": "Bad Request", "model": BadRequestResponse},
+            401: {"description": "Unauthorized", "model": UnauthenticatedResponse},
+            404: {"description": "Not Found", "model": NotFoundResponse},
+            422: {"description": "Validation Error", "model": ValidationErrorResponse},
+            500: {"description": "Internal Server Error", "model": InternalServerErrorResponse},
+        },
+    )
     return attach_routes(router=router, dbs=dbs)
 
 
 def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
-    @router.post("/memories", response_model=UserMemorySchema, status_code=200, operation_id="create_memory")
+    @router.post(
+        "/memories",
+        response_model=UserMemorySchema,
+        status_code=200,
+        operation_id="create_memory",
+        summary="Create Memory",
+        description=(
+            "Create a new user memory with content and associated topics. "
+            "Memories are used to store contextual information for users across conversations."
+        ),
+        responses={
+            200: {
+                "description": "Memory created successfully",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "memory_id": "mem-123",
+                            "memory": "User prefers technical explanations with code examples",
+                            "topics": ["preferences", "communication_style", "technical"],
+                            "user_id": "user-456",
+                            "created_at": "2024-01-15T10:30:00Z",
+                            "updated_at": "2024-01-15T10:30:00Z",
+                        }
+                    }
+                },
+            },
+            400: {"description": "Invalid request data", "model": BadRequestResponse},
+            422: {"description": "Validation error in payload", "model": ValidationErrorResponse},
+            500: {"description": "Failed to create memory", "model": InternalServerErrorResponse},
+        },
+    )
     async def create_memory(
         payload: UserMemoryCreateSchema,
-        db_id: Optional[str] = Query(default=None, description="The ID of the database to use"),
+        db_id: Optional[str] = Query(default=None, description="Database ID to use for memory storage"),
     ) -> UserMemorySchema:
         db = get_db(dbs, db_id)
         user_memory = db.upsert_user_memory(
@@ -48,35 +98,91 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
 
         return UserMemorySchema.from_dict(user_memory)  # type: ignore
 
-    @router.delete("/memories/{memory_id}", status_code=204, operation_id="delete_memory")
+    @router.delete(
+        "/memories/{memory_id}",
+        status_code=204,
+        operation_id="delete_memory",
+        summary="Delete Memory",
+        description="Permanently delete a specific user memory. This action cannot be undone.",
+        responses={
+            204: {"description": "Memory deleted successfully"},
+            404: {"description": "Memory not found", "model": NotFoundResponse},
+            500: {"description": "Failed to delete memory", "model": InternalServerErrorResponse},
+        },
+    )
     async def delete_memory(
-        memory_id: str = Path(), db_id: Optional[str] = Query(default=None, description="The ID of the database to use")
+        memory_id: str = Path(description="Memory ID to delete"),
+        db_id: Optional[str] = Query(default=None, description="Database ID to use for deletion"),
     ) -> None:
         db = get_db(dbs, db_id)
         db.delete_user_memory(memory_id=memory_id)
 
-    @router.delete("/memories", status_code=204, operation_id="delete_memories")
+    @router.delete(
+        "/memories",
+        status_code=204,
+        operation_id="delete_memories",
+        summary="Delete Multiple Memories",
+        description=(
+            "Delete multiple user memories by their IDs in a single operation. "
+            "This action cannot be undone and all specified memories will be permanently removed."
+        ),
+        responses={
+            204: {"description": "Memories deleted successfully"},
+            400: {"description": "Invalid request - empty memory_ids list", "model": BadRequestResponse},
+            500: {"description": "Failed to delete memories", "model": InternalServerErrorResponse},
+        },
+    )
     async def delete_memories(
         request: DeleteMemoriesRequest,
-        db_id: Optional[str] = Query(default=None, description="The ID of the database to use"),
+        db_id: Optional[str] = Query(default=None, description="Database ID to use for deletion"),
     ) -> None:
         db = get_db(dbs, db_id)
         db.delete_user_memories(memory_ids=request.memory_ids)
 
     @router.get(
-        "/memories", response_model=PaginatedResponse[UserMemorySchema], status_code=200, operation_id="get_memories"
+        "/memories",
+        response_model=PaginatedResponse[UserMemorySchema],
+        status_code=200,
+        operation_id="get_memories",
+        summary="List Memories",
+        description=(
+            "Retrieve paginated list of user memories with filtering and search capabilities. "
+            "Filter by user, agent, team, topics, or search within memory content."
+        ),
+        responses={
+            200: {
+                "description": "Memories retrieved successfully",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "data": [
+                                {
+                                    "memory_id": "f9361a69-2997-40c7-ae4e-a5861d434047",
+                                    "memory": "User likes coffee.",
+                                    "topics": ["preferences"],
+                                    "agent_id": None,
+                                    "team_id": None,
+                                    "user_id": "123",
+                                    "updated_at": "2025-09-01T07:53:17Z",
+                                }
+                            ]
+                        }
+                    }
+                },
+            }
+        },
     )
     async def get_memories(
         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"),
         topics: Optional[List[str]] = Depends(parse_topics),
-        search_content: Optional[str] = Query(default=None, description="Fuzzy search memory content"),
-        limit: Optional[int] = Query(default=20, description="Number of memories to return"),
-        page: Optional[int] = Query(default=1, description="Page number"),
-        sort_by: Optional[str] = Query(default="updated_at", description="Field to sort by"),
+        search_content: Optional[str] = Query(default=None, description="Fuzzy search within memory content"),
+        limit: Optional[int] = Query(default=20, description="Number of memories to return per page"),
+        page: Optional[int] = Query(default=1, description="Page number for pagination"),
+        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="The ID of the database to use"),
+        db_id: Optional[str] = Query(default=None, description="Database ID to query memories from"),
     ) -> PaginatedResponse[UserMemorySchema]:
         db = get_db(dbs, db_id)
         user_memories, total_count = db.get_user_memories(
@@ -101,10 +207,36 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
             ),
         )
 
-    @router.get("/memories/{memory_id}", response_model=UserMemorySchema, status_code=200, operation_id="get_memory")
+    @router.get(
+        "/memories/{memory_id}",
+        response_model=UserMemorySchema,
+        status_code=200,
+        operation_id="get_memory",
+        summary="Get Memory by ID",
+        description="Retrieve detailed information about a specific user memory by its ID.",
+        responses={
+            200: {
+                "description": "Memory retrieved successfully",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "memory_id": "f9361a69-2997-40c7-ae4e-a5861d434047",
+                            "memory": "User likes coffee.",
+                            "topics": ["preferences"],
+                            "agent_id": None,
+                            "team_id": None,
+                            "user_id": "123",
+                            "updated_at": "2025-09-01T07:53:17Z",
+                        }
+                    }
+                },
+            },
+            404: {"description": "Memory not found", "model": NotFoundResponse},
+        },
+    )
     async def get_memory(
-        memory_id: str = Path(),
-        db_id: Optional[str] = Query(default=None, description="The ID of the database to use"),
+        memory_id: str = Path(description="Memory ID to retrieve"),
+        db_id: Optional[str] = Query(default=None, description="Database ID to query memory from"),
     ) -> UserMemorySchema:
         db = get_db(dbs, db_id)
         user_memory = db.get_user_memory(memory_id=memory_id, deserialize=False)
@@ -113,20 +245,80 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
 
         return UserMemorySchema.from_dict(user_memory)  # type: ignore
 
-    @router.get("/memories/topics", response_model=List[str], status_code=200, operation_id="get_memory_topics")
+    @router.get(
+        "/memory_topics",
+        response_model=List[str],
+        status_code=200,
+        operation_id="get_memory_topics",
+        summary="Get Memory Topics",
+        description=(
+            "Retrieve all unique topics associated with memories in the system. "
+            "Useful for filtering and categorizing memories by topic."
+        ),
+        responses={
+            200: {
+                "description": "Memory topics retrieved successfully",
+                "content": {
+                    "application/json": {
+                        "example": [
+                            "preferences",
+                            "communication_style",
+                            "technical",
+                            "industry",
+                            "compliance",
+                            "code_examples",
+                            "requirements",
+                            "healthcare",
+                            "finance",
+                        ]
+                    }
+                },
+            }
+        },
+    )
     async def get_topics(
-        db_id: Optional[str] = Query(default=None, description="The ID of the database to use"),
+        db_id: Optional[str] = Query(default=None, description="Database ID to query topics from"),
     ) -> List[str]:
         db = get_db(dbs, db_id)
         return db.get_all_memory_topics()
 
     @router.patch(
-        "/memories/{memory_id}", response_model=UserMemorySchema, status_code=200, operation_id="update_memory"
+        "/memories/{memory_id}",
+        response_model=UserMemorySchema,
+        status_code=200,
+        operation_id="update_memory",
+        summary="Update Memory",
+        description=(
+            "Update an existing user memory's content and topics. "
+            "Replaces the entire memory content and topic list with the provided values."
+        ),
+        responses={
+            200: {
+                "description": "Memory updated successfully",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "memory_id": "f9361a69-2997-40c7-ae4e-a5861d434047",
+                            "memory": "User likes coffee.",
+                            "topics": ["preferences"],
+                            "agent_id": None,
+                            "team_id": None,
+                            "user_id": "123",
+                            "updated_at": "2025-09-01T07:53:17Z",
+                        }
+                    }
+                },
+            },
+            400: {"description": "Invalid request data", "model": BadRequestResponse},
+            404: {"description": "Memory not found", "model": NotFoundResponse},
+            422: {"description": "Validation error in payload", "model": ValidationErrorResponse},
+            500: {"description": "Failed to update memory", "model": InternalServerErrorResponse},
+        },
     )
     async def update_memory(
         payload: UserMemoryCreateSchema,
-        memory_id: str = Path(),
-        db_id: Optional[str] = Query(default=None, description="The ID of the database to use"),
+        memory_id: str = Path(description="Memory ID to update"),
+        db_id: Optional[str] = Query(default=None, description="Database ID to use for update"),
     ) -> UserMemorySchema:
         db = get_db(dbs, db_id)
         user_memory = db.upsert_user_memory(
@@ -148,11 +340,35 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         response_model=PaginatedResponse[UserStatsSchema],
         status_code=200,
         operation_id="get_user_memory_stats",
+        summary="Get User Memory Statistics",
+        description=(
+            "Retrieve paginated statistics about memory usage by user. "
+            "Provides insights into user engagement and memory distribution across users."
+        ),
+        responses={
+            200: {
+                "description": "User memory statistics retrieved successfully",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "data": [
+                                {
+                                    "user_id": "123",
+                                    "total_memories": 3,
+                                    "last_memory_updated_at": "2025-09-01T07:53:17Z",
+                                }
+                            ]
+                        }
+                    }
+                },
+            },
+            500: {"description": "Failed to retrieve user statistics", "model": InternalServerErrorResponse},
+        },
     )
     async def get_user_memory_stats(
-        limit: Optional[int] = Query(default=20, description="Number of items to return"),
-        page: Optional[int] = Query(default=1, description="Page number"),
-        db_id: Optional[str] = Query(default=None, description="The ID of the database to use"),
+        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"),
     ) -> PaginatedResponse[UserStatsSchema]:
         db = get_db(dbs, db_id)
         try:
@@ -176,8 +392,14 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
     return router
 
 
-def parse_topics(topics: Optional[List[str]] = Query(default=None)) -> Optional[List[str]]:
-    """Parse a comma-separated string of topics into a list of topics"""
+def parse_topics(
+    topics: Optional[List[str]] = Query(
+        default=None,
+        description="Comma-separated list of topics to filter by",
+        example=["preferences,technical,communication_style"],
+    ),
+) -> Optional[List[str]]:
+    """Parse comma-separated topics into a list for filtering memories by topic."""
     if not topics:
         return None
 
@@ -185,4 +407,4 @@ def parse_topics(topics: Optional[List[str]] = Query(default=None)) -> Optional[
         return [topic.strip() for topic in topics[0].split(",") if topic.strip()]
 
     except Exception as e:
-        raise HTTPException(status_code=422, detail=f"Invalid topics: {e}")
+        raise HTTPException(status_code=422, detail=f"Invalid topics format: {e}")

agno/os/routers/metrics/metrics.py

@@ -8,6 +8,13 @@ from fastapi.routing import APIRouter
 from agno.db.base import BaseDb
 from agno.os.auth import get_authentication_dependency
 from agno.os.routers.metrics.schemas import DayAggregatedMetrics, MetricsResponse
+from agno.os.schema import (
+    BadRequestResponse,
+    InternalServerErrorResponse,
+    NotFoundResponse,
+    UnauthenticatedResponse,
+    ValidationErrorResponse,
+)
 from agno.os.settings import AgnoAPISettings
 from agno.os.utils import get_db
 
@@ -15,16 +22,81 @@ logger = logging.getLogger(__name__)
 
 
 def get_metrics_router(dbs: dict[str, BaseDb], settings: AgnoAPISettings = AgnoAPISettings(), **kwargs) -> APIRouter:
-    router = APIRouter(dependencies=[Depends(get_authentication_dependency(settings))], tags=["Metrics"])
+    """Create metrics router with comprehensive OpenAPI documentation for system metrics and analytics endpoints."""
+    router = APIRouter(
+        dependencies=[Depends(get_authentication_dependency(settings))],
+        tags=["Metrics"],
+        responses={
+            400: {"description": "Bad Request", "model": BadRequestResponse},
+            401: {"description": "Unauthorized", "model": UnauthenticatedResponse},
+            404: {"description": "Not Found", "model": NotFoundResponse},
+            422: {"description": "Validation Error", "model": ValidationErrorResponse},
+            500: {"description": "Internal Server Error", "model": InternalServerErrorResponse},
+        },
+    )
     return attach_routes(router=router, dbs=dbs)
 
 
 def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
-    @router.get("/metrics", response_model=MetricsResponse, status_code=200, operation_id="get_metrics")
+    @router.get(
+        "/metrics",
+        response_model=MetricsResponse,
+        status_code=200,
+        operation_id="get_metrics",
+        summary="Get AgentOS Metrics",
+        description=(
+            "Retrieve AgentOS metrics and analytics data for a specified date range. "
+            "If no date range is specified, returns all available metrics."
+        ),
+        responses={
+            200: {
+                "description": "Metrics retrieved successfully",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "metrics": [
+                                {
+                                    "id": "7bf39658-a00a-484c-8a28-67fd8a9ddb2a",
+                                    "agent_runs_count": 5,
+                                    "agent_sessions_count": 5,
+                                    "team_runs_count": 0,
+                                    "team_sessions_count": 0,
+                                    "workflow_runs_count": 0,
+                                    "workflow_sessions_count": 0,
+                                    "users_count": 1,
+                                    "token_metrics": {
+                                        "input_tokens": 448,
+                                        "output_tokens": 148,
+                                        "total_tokens": 596,
+                                        "audio_tokens": 0,
+                                        "input_audio_tokens": 0,
+                                        "output_audio_tokens": 0,
+                                        "cached_tokens": 0,
+                                        "cache_write_tokens": 0,
+                                        "reasoning_tokens": 0,
+                                    },
+                                    "model_metrics": [{"model_id": "gpt-4o", "model_provider": "OpenAI", "count": 5}],
+                                    "date": "2025-07-31T00:00:00",
+                                    "created_at": 1753993132,
+                                    "updated_at": 1753993741,
+                                }
+                            ]
+                        }
+                    }
+                },
+            },
+            400: {"description": "Invalid date range parameters", "model": BadRequestResponse},
+            500: {"description": "Failed to retrieve metrics", "model": InternalServerErrorResponse},
+        },
+    )
     async def get_metrics(
-        starting_date: Optional[date] = Query(default=None, description="Starting date to filter metrics (YYYY-MM-DD)"),
-        ending_date: Optional[date] = Query(default=None, description="Ending date to filter metrics (YYYY-MM-DD)"),
-        db_id: Optional[str] = Query(default=None, description="The ID of the database to use"),
+        starting_date: Optional[date] = Query(
+            default=None, description="Starting date for metrics range (YYYY-MM-DD format)"
+        ),
+        ending_date: Optional[date] = Query(
+            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"),
     ) -> MetricsResponse:
         try:
             db = get_db(dbs, db_id)
@@ -41,10 +113,56 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
             raise HTTPException(status_code=500, detail=f"Error getting metrics: {str(e)}")
 
     @router.post(
-        "/metrics/refresh", response_model=List[DayAggregatedMetrics], status_code=200, operation_id="refresh_metrics"
+        "/metrics/refresh",
+        response_model=List[DayAggregatedMetrics],
+        status_code=200,
+        operation_id="refresh_metrics",
+        summary="Refresh Metrics",
+        description=(
+            "Manually trigger recalculation of system metrics from raw data. "
+            "This operation analyzes system activity logs and regenerates aggregated metrics. "
+            "Useful for ensuring metrics are up-to-date or after system maintenance."
+        ),
+        responses={
+            200: {
+                "description": "Metrics refreshed successfully",
+                "content": {
+                    "application/json": {
+                        "example": [
+                            {
+                                "id": "e77c9531-818b-47a5-99cd-59fed61e5403",
+                                "agent_runs_count": 2,
+                                "agent_sessions_count": 2,
+                                "team_runs_count": 0,
+                                "team_sessions_count": 0,
+                                "workflow_runs_count": 0,
+                                "workflow_sessions_count": 0,
+                                "users_count": 1,
+                                "token_metrics": {
+                                    "input_tokens": 256,
+                                    "output_tokens": 441,
+                                    "total_tokens": 697,
+                                    "audio_total_tokens": 0,
+                                    "audio_input_tokens": 0,
+                                    "audio_output_tokens": 0,
+                                    "cache_read_tokens": 0,
+                                    "cache_write_tokens": 0,
+                                    "reasoning_tokens": 0,
+                                },
+                                "model_metrics": [{"model_id": "gpt-4o", "model_provider": "OpenAI", "count": 2}],
+                                "date": "2025-08-12T00:00:00",
+                                "created_at": 1755016907,
+                                "updated_at": 1755016907,
+                            }
+                        ]
+                    }
+                },
+            },
+            500: {"description": "Failed to refresh metrics", "model": InternalServerErrorResponse},
+        },
     )
     async def calculate_metrics(
-        db_id: Optional[str] = Query(default=None, description="The ID of the database to use"),
+        db_id: Optional[str] = Query(default=None, description="Database ID to use for metrics calculation"),
     ) -> List[DayAggregatedMetrics]:
         try:
             db = get_db(dbs, db_id)