agno 1.8.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

agno/os/routers/knowledge/schemas.py

@@ -0,0 +1,118 @@
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ContentStatus(str, Enum):
+    """Enumeration of possible content processing statuses."""
+
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class ContentStatusResponse(BaseModel):
+    """Response model for content status endpoint."""
+
+    status: ContentStatus
+    status_message: str = ""
+
+
+class ContentResponseSchema(BaseModel):
+    id: str
+    name: Optional[str] = None
+    description: Optional[str] = None
+    type: Optional[str] = None
+    size: Optional[str] = None
+    linked_to: Optional[str] = None
+    metadata: Optional[dict] = None
+    access_count: Optional[int] = None
+    status: Optional[ContentStatus] = None
+    status_message: Optional[str] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+    @classmethod
+    def from_dict(cls, content: Dict[str, Any]) -> "ContentResponseSchema":
+        status = content.get("status")
+        if isinstance(status, str):
+            try:
+                status = ContentStatus(status.lower())
+            except ValueError:
+                # Handle legacy or unknown statuses gracefully
+                if "failed" in status.lower():
+                    status = ContentStatus.FAILED
+                elif "completed" in status.lower():
+                    status = ContentStatus.COMPLETED
+                else:
+                    status = ContentStatus.PROCESSING
+        elif status is None:
+            status = ContentStatus.PROCESSING  # Default for None values
+
+        # Helper function to safely parse timestamps
+        def parse_timestamp(timestamp_value):
+            if timestamp_value is None:
+                return None
+            try:
+                # If it's already a datetime object, return it
+                if isinstance(timestamp_value, datetime):
+                    return timestamp_value
+                # If it's a string, try to parse it as ISO format first
+                if isinstance(timestamp_value, str):
+                    try:
+                        return datetime.fromisoformat(timestamp_value.replace("Z", "+00:00"))
+                    except ValueError:
+                        # Try to parse as float/int timestamp
+                        timestamp_value = float(timestamp_value)
+                # If it's a number, use fromtimestamp
+                return datetime.fromtimestamp(timestamp_value, tz=timezone.utc)
+            except (ValueError, TypeError, OSError):
+                # If all parsing fails, return None
+                return None
+
+        return cls(
+            id=content.get("id"),  # type: ignore
+            name=content.get("name"),
+            description=content.get("description"),
+            type=content.get("file_type"),
+            size=str(content.get("size")) if content.get("size") else "0",
+            metadata=content.get("metadata"),
+            status=status,
+            status_message=content.get("status_message"),
+            created_at=parse_timestamp(content.get("created_at")),
+            updated_at=parse_timestamp(content.get("updated_at")),
+            # TODO: These fields are not available in the Content class. Fix the inconsistency
+            access_count=None,
+            linked_to=None,
+        )
+
+
+class ContentUpdateSchema(BaseModel):
+    """Schema for updating content."""
+
+    name: Optional[str] = Field(None, description="Content name", min_length=1, max_length=255)
+    description: Optional[str] = Field(None, description="Content description", max_length=1000)
+    metadata: Optional[Dict[str, Any]] = Field(None, description="Content metadata as key-value pairs")
+    reader_id: Optional[str] = Field(None, description="ID of the reader to use for processing", min_length=1)
+
+
+class ReaderSchema(BaseModel):
+    id: str
+    name: Optional[str] = None
+    description: Optional[str] = None
+    chunkers: Optional[List[str]] = None
+
+
+class ChunkerSchema(BaseModel):
+    key: str
+    name: Optional[str] = None
+    description: Optional[str] = None
+
+
+class ConfigResponseSchema(BaseModel):
+    readers: Optional[Dict[str, ReaderSchema]] = None
+    readersForType: Optional[Dict[str, List[str]]] = None
+    chunkers: Optional[Dict[str, ChunkerSchema]] = None
+    filters: Optional[List[str]] = None

agno/os/routers/memory/__init__.py

@@ -0,0 +1,3 @@
+from agno.os.routers.memory.memory import get_memory_router
+
+__all__ = ["get_memory_router"]

agno/os/routers/memory/memory.py

@@ -0,0 +1,410 @@
+import logging
+import math
+from typing import List, Optional
+from uuid import uuid4
+
+from fastapi import Depends, HTTPException, Path, Query
+from fastapi.routing import APIRouter
+
+from agno.db.base import BaseDb
+from agno.db.schemas import UserMemory
+from agno.os.auth import get_authentication_dependency
+from agno.os.routers.memory.schemas import (
+    DeleteMemoriesRequest,
+    UserMemoryCreateSchema,
+    UserMemorySchema,
+    UserStatsSchema,
+)
+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
+
+logger = logging.getLogger(__name__)
+
+
+def get_memory_router(dbs: dict[str, BaseDb], 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))],
+        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",
+        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="Database ID 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 not user_memory:
+            raise HTTPException(status_code=500, detail="Failed to create memory")
+
+        return UserMemorySchema.from_dict(user_memory)  # type: ignore
+
+    @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(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",
+        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="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",
+        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 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="Database ID to query memories from"),
+    ) -> 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,
+        )
+        return PaginatedResponse(
+            data=[UserMemorySchema.from_dict(user_memory) for user_memory in user_memories],  # type: ignore
+            meta=PaginationInfo(
+                page=page,
+                limit=limit,
+                total_count=total_count,  # type: ignore
+                total_pages=math.ceil(total_count / limit) if limit is not None and limit > 0 else 0,  # type: ignore
+            ),
+        )
+
+    @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(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)
+        if not user_memory:
+            raise HTTPException(status_code=404, detail=f"Memory with ID {memory_id} not found")
+
+        return UserMemorySchema.from_dict(user_memory)  # type: ignore
+
+    @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="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",
+        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(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(
+            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")
+
+        return UserMemorySchema.from_dict(user_memory)  # type: ignore
+
+    @router.get(
+        "/user_memory_stats",
+        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 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:
+            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(
+                    page=page,
+                    limit=limit,
+                    total_count=total_count,
+                    total_pages=(total_count + limit - 1) // limit if limit is not None and limit > 0 else 0,
+                ),
+            )
+
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Failed to get user statistics: {str(e)}")
+
+    return router
+
+
+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
+
+    try:
+        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 format: {e}")

agno/os/routers/memory/schemas.py

@@ -0,0 +1,58 @@
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel
+
+
+class DeleteMemoriesRequest(BaseModel):
+    memory_ids: List[str]
+
+
+class UserMemorySchema(BaseModel):
+    memory_id: str
+    memory: str
+    topics: Optional[List[str]]
+
+    agent_id: Optional[str]
+    team_id: Optional[str]
+    user_id: Optional[str]
+
+    updated_at: Optional[datetime]
+
+    @classmethod
+    def from_dict(cls, memory_dict: Dict[str, Any]) -> "UserMemorySchema":
+        return cls(
+            memory_id=memory_dict["memory_id"],
+            user_id=str(memory_dict["user_id"]),
+            agent_id=memory_dict.get("agent_id"),
+            team_id=memory_dict.get("team_id"),
+            memory=memory_dict["memory"],
+            topics=memory_dict.get("topics", []),
+            updated_at=memory_dict["updated_at"],
+        )
+
+
+class UserMemoryCreateSchema(BaseModel):
+    """Define the payload expected for creating a new user memory"""
+
+    memory: str
+    user_id: str
+    topics: Optional[List[str]] = None
+
+
+class UserStatsSchema(BaseModel):
+    """Schema for user memory statistics"""
+
+    user_id: str
+    total_memories: int
+    last_memory_updated_at: Optional[datetime] = None
+
+    @classmethod
+    def from_dict(cls, user_stats_dict: Dict[str, Any]) -> "UserStatsSchema":
+        updated_at = user_stats_dict.get("last_memory_updated_at")
+
+        return cls(
+            user_id=str(user_stats_dict["user_id"]),
+            total_memories=user_stats_dict["total_memories"],
+            last_memory_updated_at=datetime.fromtimestamp(updated_at, tz=timezone.utc) if updated_at else None,
+        )

agno/os/routers/metrics/__init__.py

@@ -0,0 +1,3 @@
+from agno.os.routers.metrics.metrics import get_metrics_router
+
+__all__ = ["get_metrics_router"]