agno 2.1.2__py3-none-any.whl → 2.3.13__py3-none-any.whl

agno/os/routers/knowledge/schemas.py

@@ -16,23 +16,23 @@ class ContentStatus(str, Enum):
 class ContentStatusResponse(BaseModel):
     """Response model for content status endpoint."""
 
-    status: ContentStatus
-    status_message: str = ""
+    status: ContentStatus = Field(..., description="Current processing status of the content")
+    status_message: str = Field("", description="Status message or error details")
 
 
 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
+    id: str = Field(..., description="Unique identifier for the content")
+    name: Optional[str] = Field(None, description="Name of the content")
+    description: Optional[str] = Field(None, description="Description of the content")
+    type: Optional[str] = Field(None, description="MIME type of the content")
+    size: Optional[str] = Field(None, description="Size of the content in bytes")
+    linked_to: Optional[str] = Field(None, description="ID of related content if linked")
+    metadata: Optional[dict] = Field(None, description="Additional metadata as key-value pairs")
+    access_count: Optional[int] = Field(None, description="Number of times content has been accessed", ge=0)
+    status: Optional[ContentStatus] = Field(None, description="Processing status of the content")
+    status_message: Optional[str] = Field(None, description="Status message or error details")
+    created_at: Optional[datetime] = Field(None, description="Timestamp when content was created")
+    updated_at: Optional[datetime] = Field(None, description="Timestamp when content was last updated")
 
     @classmethod
     def from_dict(cls, content: Dict[str, Any]) -> "ContentResponseSchema":
@@ -99,20 +99,80 @@ class ContentUpdateSchema(BaseModel):
 
 
 class ReaderSchema(BaseModel):
-    id: str
-    name: Optional[str] = None
-    description: Optional[str] = None
-    chunkers: Optional[List[str]] = None
+    id: str = Field(..., description="Unique identifier for the reader")
+    name: Optional[str] = Field(None, description="Name of the reader")
+    description: Optional[str] = Field(None, description="Description of the reader's capabilities")
+    chunkers: Optional[List[str]] = Field(None, description="List of supported chunking strategies")
 
 
 class ChunkerSchema(BaseModel):
     key: str
     name: Optional[str] = None
     description: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class VectorDbSchema(BaseModel):
+    id: str = Field(..., description="Unique identifier for the vector database")
+    name: Optional[str] = Field(None, description="Name of the vector database")
+    description: Optional[str] = Field(None, description="Description of the vector database")
+    search_types: Optional[List[str]] = Field(
+        None, description="List of supported search types (vector, keyword, hybrid)"
+    )
+
+
+class VectorSearchResult(BaseModel):
+    """Schema for search result documents."""
+
+    id: str = Field(..., description="Unique identifier for the search result document")
+    content: str = Field(..., description="Content text of the document")
+    name: Optional[str] = Field(None, description="Name of the document")
+    meta_data: Optional[Dict[str, Any]] = Field(None, description="Metadata associated with the document")
+    usage: Optional[Dict[str, Any]] = Field(None, description="Usage statistics (e.g., token counts)")
+    reranking_score: Optional[float] = Field(None, description="Reranking score for relevance", ge=0.0, le=1.0)
+    content_id: Optional[str] = Field(None, description="ID of the source content")
+    content_origin: Optional[str] = Field(None, description="Origin URL or source of the content")
+    size: Optional[int] = Field(None, description="Size of the content in bytes", ge=0)
+
+    @classmethod
+    def from_document(cls, document) -> "VectorSearchResult":
+        """Convert a Document object to a serializable VectorSearchResult."""
+        return cls(
+            id=document.id,
+            content=document.content,
+            name=getattr(document, "name", None),
+            meta_data=getattr(document, "meta_data", None),
+            usage=getattr(document, "usage", None),
+            reranking_score=getattr(document, "reranking_score", None),
+            content_id=getattr(document, "content_id", None),
+            content_origin=getattr(document, "content_origin", None),
+            size=getattr(document, "size", None),
+        )
+
+
+class VectorSearchRequestSchema(BaseModel):
+    """Schema for vector search request."""
+
+    class Meta(BaseModel):
+        """Inline metadata schema for pagination."""
+
+        limit: int = Field(20, description="Number of results per page", ge=1, le=100)
+        page: int = Field(1, description="Page number", ge=1)
+
+    query: str = Field(..., description="The search query text")
+    db_id: Optional[str] = Field(None, description="The content database ID to search in")
+    vector_db_ids: Optional[List[str]] = Field(None, description="List of vector database IDs to search in")
+    search_type: Optional[str] = Field(None, description="The type of search to perform (vector, keyword, hybrid)")
+    max_results: Optional[int] = Field(None, description="The maximum number of results to return", ge=1, le=1000)
+    filters: Optional[Dict[str, Any]] = Field(None, description="Filters to apply to the search results")
+    meta: Optional[Meta] = Field(
+        None, description="Pagination metadata. Limit and page number to return a subset of results."
+    )
 
 
 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
+    readers: Optional[Dict[str, ReaderSchema]] = Field(None, description="Available content readers")
+    readersForType: Optional[Dict[str, List[str]]] = Field(None, description="Mapping of content types to reader IDs")
+    chunkers: Optional[Dict[str, ChunkerSchema]] = Field(None, description="Available chunking strategies")
+    filters: Optional[List[str]] = Field(None, description="Available filter tags")
+    vector_dbs: Optional[List[VectorDbSchema]] = Field(None, description="Configured vector databases")

agno/os/routers/memory/memory.py

@@ -1,16 +1,19 @@
 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, 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.models.utils import get_model
 from agno.os.auth import get_authentication_dependency
 from agno.os.routers.memory.schemas import (
     DeleteMemoriesRequest,
+    OptimizeMemoriesRequest,
+    OptimizeMemoriesResponse,
     UserMemoryCreateSchema,
     UserMemorySchema,
     UserStatsSchema,
@@ -31,7 +34,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 +52,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,
@@ -83,6 +88,7 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         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:
         if hasattr(request.state, "user_id"):
             user_id = request.state.user_id
@@ -91,16 +97,30 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         if payload.user_id is None:
             raise HTTPException(status_code=400, detail="User ID is required")
 
-        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,
-        )
+        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")
 
@@ -122,9 +142,14 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         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, user_id=user_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",
@@ -144,9 +169,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, user_id=request.user_id)
+        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",
@@ -193,26 +223,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)
+        db = await get_db(dbs, db_id, table)
 
         if hasattr(request.state, "user_id"):
             user_id = request.state.user_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,
-        )
+        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,
@@ -249,12 +297,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, user_id=user_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")
 
@@ -293,9 +351,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}",
@@ -335,9 +398,8 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         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)
-
         if hasattr(request.state, "user_id"):
             user_id = request.state.user_id
             payload.user_id = user_id
@@ -345,15 +407,29 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         if payload.user_id is None:
             raise HTTPException(status_code=400, detail="User ID is required")
 
-        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,
-        )
+        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")
 
@@ -393,13 +469,24 @@ 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,
-            )
+            # Ensure limit and page are integers
+            limit = int(limit) if limit is not None else 20
+            page = int(page) if page is not None else 1
+            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(
@@ -413,6 +500,146 @@ def attach_routes(router: APIRouter, dbs: dict[str, BaseDb]) -> APIRouter:
         except Exception as e:
             raise HTTPException(status_code=500, detail=f"Failed to get user statistics: {str(e)}")
 
+    @router.post(
+        "/optimize-memories",
+        response_model=OptimizeMemoriesResponse,
+        status_code=200,
+        operation_id="optimize_memories",
+        summary="Optimize User Memories",
+        description=(
+            "Optimize all memories for a given user using the default summarize strategy. "
+            "This operation combines all memories into a single comprehensive summary, "
+            "achieving maximum token reduction while preserving all key information. "
+            "To use a custom model, specify the model parameter in 'provider:model_id' format "
+            "(e.g., 'openai:gpt-4o-mini', 'anthropic:claude-3-5-sonnet-20241022'). "
+            "If not specified, uses MemoryManager's default model (gpt-4o). "
+            "Set apply=false to preview optimization results without saving to database."
+        ),
+        responses={
+            200: {
+                "description": "Memories optimized successfully",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "memories": [
+                                {
+                                    "memory_id": "f9361a69-2997-40c7-ae4e-a5861d434047",
+                                    "memory": "User has a 3-year-old golden retriever named Max who loves fetch and walks. Lives in San Francisco's Mission district, works as a product manager in tech. Enjoys hiking Bay Area trails, trying new restaurants (especially Japanese, Thai, Mexican), and learning piano for 1.5 years.",
+                                    "topics": ["pets", "location", "work", "hobbies", "food_preferences"],
+                                    "user_id": "user2",
+                                    "updated_at": "2025-11-18T10:30:00Z",
+                                }
+                            ],
+                            "memories_before": 4,
+                            "memories_after": 1,
+                            "tokens_before": 450,
+                            "tokens_after": 180,
+                            "tokens_saved": 270,
+                            "reduction_percentage": 60.0,
+                        }
+                    }
+                },
+            },
+            400: {
+                "description": "Bad request - User ID is required or invalid model string format",
+                "model": BadRequestResponse,
+            },
+            404: {"description": "No memories found for user", "model": NotFoundResponse},
+            500: {"description": "Failed to optimize memories", "model": InternalServerErrorResponse},
+        },
+    )
+    async def optimize_memories(
+        request: OptimizeMemoriesRequest,
+        db_id: Optional[str] = Query(default=None, description="Database ID to use for optimization"),
+        table: Optional[str] = Query(default=None, description="Table to use for optimization"),
+    ) -> OptimizeMemoriesResponse:
+        """Optimize user memories using the default summarize strategy."""
+        from agno.memory import MemoryManager
+        from agno.memory.strategies.types import MemoryOptimizationStrategyType
+
+        try:
+            # Get database instance
+            db = await get_db(dbs, db_id, table)
+
+            # Create memory manager with optional model
+            if request.model:
+                try:
+                    model_instance = get_model(request.model)
+                except ValueError as e:
+                    raise HTTPException(status_code=400, detail=str(e))
+                memory_manager = MemoryManager(model=model_instance, db=db)
+            else:
+                # No model specified - use MemoryManager's default
+                memory_manager = MemoryManager(db=db)
+
+            # Get current memories to count tokens before optimization
+            if isinstance(db, AsyncBaseDb):
+                memories_before = await memory_manager.aget_user_memories(user_id=request.user_id)
+            else:
+                memories_before = memory_manager.get_user_memories(user_id=request.user_id)
+
+            if not memories_before:
+                raise HTTPException(status_code=404, detail=f"No memories found for user {request.user_id}")
+
+            # Count tokens before optimization
+            from agno.memory.strategies.summarize import SummarizeStrategy
+
+            strategy = SummarizeStrategy()
+            tokens_before = strategy.count_tokens(memories_before)
+            memories_before_count = len(memories_before)
+
+            # Optimize memories with default SUMMARIZE strategy
+            if isinstance(db, AsyncBaseDb):
+                optimized_memories = await memory_manager.aoptimize_memories(
+                    user_id=request.user_id,
+                    strategy=MemoryOptimizationStrategyType.SUMMARIZE,
+                    apply=request.apply,
+                )
+            else:
+                optimized_memories = memory_manager.optimize_memories(
+                    user_id=request.user_id,
+                    strategy=MemoryOptimizationStrategyType.SUMMARIZE,
+                    apply=request.apply,
+                )
+
+            # Count tokens after optimization
+            tokens_after = strategy.count_tokens(optimized_memories)
+            memories_after_count = len(optimized_memories)
+
+            # Calculate statistics
+            tokens_saved = tokens_before - tokens_after
+            reduction_percentage = (tokens_saved / tokens_before * 100.0) if tokens_before > 0 else 0.0
+
+            # Convert to schema objects
+            optimized_memory_schemas = [
+                UserMemorySchema(
+                    memory_id=mem.memory_id or "",
+                    memory=mem.memory or "",
+                    topics=mem.topics,
+                    agent_id=mem.agent_id,
+                    team_id=mem.team_id,
+                    user_id=mem.user_id,
+                    updated_at=mem.updated_at,
+                )
+                for mem in optimized_memories
+            ]
+
+            return OptimizeMemoriesResponse(
+                memories=optimized_memory_schemas,
+                memories_before=memories_before_count,
+                memories_after=memories_after_count,
+                tokens_before=tokens_before,
+                tokens_after=tokens_after,
+                tokens_saved=tokens_saved,
+                reduction_percentage=reduction_percentage,
+            )
+
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Failed to optimize memories for user {request.user_id}: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Failed to optimize memories: {str(e)}")
+
     return router