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

agno/os/routers/memory/schemas.py

@@ -0,0 +1,88 @@
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class DeleteMemoriesRequest(BaseModel):
+    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 = 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] = 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] = Field(None, description="Timestamp when memory was last updated")
+
+    @classmethod
+    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"]),
+            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 = 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 = 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":
+        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,
+        )
+
+
+class OptimizeMemoriesRequest(BaseModel):
+    """Schema for memory optimization request"""
+
+    user_id: str = Field(..., description="User ID to optimize memories for")
+    model: Optional[str] = Field(
+        default=None,
+        description="Model to use for optimization in format 'provider:model_id' (e.g., 'openai:gpt-4o-mini', 'anthropic:claude-3-5-sonnet-20241022', 'google:gemini-2.0-flash-exp'). If not specified, uses MemoryManager's default model (gpt-4o).",
+    )
+    apply: bool = Field(
+        default=True,
+        description="If True, apply optimization changes to database. If False, return preview only without saving.",
+    )
+
+
+class OptimizeMemoriesResponse(BaseModel):
+    """Schema for memory optimization response"""
+
+    memories: List[UserMemorySchema] = Field(..., description="List of optimized memory objects")
+    memories_before: int = Field(..., description="Number of memories before optimization", ge=0)
+    memories_after: int = Field(..., description="Number of memories after optimization", ge=0)
+    tokens_before: int = Field(..., description="Token count before optimization", ge=0)
+    tokens_after: int = Field(..., description="Token count after optimization", ge=0)
+    tokens_saved: int = Field(..., description="Number of tokens saved through optimization", ge=0)
+    reduction_percentage: float = Field(..., description="Percentage of token reduction achieved", ge=0.0, le=100.0)

agno/os/routers/metrics/__init__.py

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

agno/os/routers/metrics/metrics.py

@@ -0,0 +1,190 @@
+import logging
+from datetime import date, datetime, timezone
+from typing import List, Optional, Union, cast
+
+from fastapi import Depends, HTTPException, Query
+from fastapi.routing import APIRouter
+
+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 (
+    BadRequestResponse,
+    InternalServerErrorResponse,
+    NotFoundResponse,
+    UnauthenticatedResponse,
+    ValidationErrorResponse,
+)
+from agno.os.settings import AgnoAPISettings
+from agno.os.utils import get_db
+
+logger = logging.getLogger(__name__)
+
+
+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))],
+        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, list[Union[BaseDb, AsyncBaseDb]]]) -> APIRouter:
+    @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 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"),
+        table: Optional[str] = Query(default=None, description="The database table to use"),
+    ) -> MetricsResponse:
+        try:
+            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],
+                updated_at=datetime.fromtimestamp(latest_updated_at, tz=timezone.utc)
+                if latest_updated_at is not None
+                else None,
+            )
+
+        except Exception as e:
+            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",
+        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="Database ID to use for metrics calculation"),
+        table: Optional[str] = Query(default=None, description="Table to use for metrics calculation"),
+    ) -> List[DayAggregatedMetrics]:
+        try:
+            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 []
+
+            return [DayAggregatedMetrics.from_dict(metric) for metric in result]
+
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Error refreshing metrics: {str(e)}")
+
+    return router

agno/os/routers/metrics/schemas.py

@@ -0,0 +1,47 @@
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class DayAggregatedMetrics(BaseModel):
+    """Aggregated metrics for a given day"""
+
+    id: str = Field(..., description="Unique identifier for the metrics record")
+
+    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 = 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":
+        return cls(
+            agent_runs_count=metrics_dict.get("agent_runs_count", 0),
+            agent_sessions_count=metrics_dict.get("agent_sessions_count", 0),
+            created_at=metrics_dict.get("created_at", 0),
+            date=metrics_dict.get("date", datetime.now()),
+            id=metrics_dict.get("id", ""),
+            model_metrics=metrics_dict.get("model_metrics", {}),
+            team_runs_count=metrics_dict.get("team_runs_count", 0),
+            team_sessions_count=metrics_dict.get("team_sessions_count", 0),
+            token_metrics=metrics_dict.get("token_metrics", {}),
+            updated_at=metrics_dict.get("updated_at", 0),
+            users_count=metrics_dict.get("users_count", 0),
+            workflow_runs_count=metrics_dict.get("workflow_runs_count", 0),
+            workflow_sessions_count=metrics_dict.get("workflow_sessions_count", 0),
+        )
+
+
+class MetricsResponse(BaseModel):
+    metrics: List[DayAggregatedMetrics] = Field(..., description="List of daily aggregated metrics")
+    updated_at: Optional[datetime] = Field(None, description="Timestamp of the most recent metrics update")

agno/os/routers/session/__init__.py

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