agno 2.1.10__py3-none-any.whl → 2.2.1__py3-none-any.whl

agno/os/routers/metrics/schemas.py

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

agno/os/routers/session/session.py

@@ -1,5 +1,7 @@
 import logging
-from typing import List, Optional, Union, cast
+import time
+from typing import Any, List, Optional, Union, cast
+from uuid import uuid4
 
 from fastapi import APIRouter, Body, Depends, HTTPException, Path, Query, Request
 
@@ -8,6 +10,7 @@ from agno.os.auth import get_authentication_dependency
 from agno.os.schema import (
     AgentSessionDetailSchema,
     BadRequestResponse,
+    CreateSessionRequest,
     DeleteSessionRequest,
     InternalServerErrorResponse,
     NotFoundResponse,
@@ -19,12 +22,14 @@ from agno.os.schema import (
     TeamRunSchema,
     TeamSessionDetailSchema,
     UnauthenticatedResponse,
+    UpdateSessionRequest,
     ValidationErrorResponse,
     WorkflowRunSchema,
     WorkflowSessionDetailSchema,
 )
 from agno.os.settings import AgnoAPISettings
 from agno.os.utils import get_db
+from agno.session import AgentSession, TeamSession, WorkflowSession
 
 logger = logging.getLogger(__name__)
 
@@ -146,6 +151,133 @@ def attach_routes(router: APIRouter, dbs: dict[str, Union[BaseDb, AsyncBaseDb]])
             ),
         )
 
+    @router.post(
+        "/sessions",
+        response_model=Union[AgentSessionDetailSchema, TeamSessionDetailSchema, WorkflowSessionDetailSchema],
+        status_code=201,
+        operation_id="create_session",
+        summary="Create New Session",
+        description=(
+            "Create a new empty session with optional configuration. "
+            "Useful for pre-creating sessions with specific session_state, metadata, or other properties "
+            "before running any agent/team/workflow interactions. "
+            "The session can later be used by providing its session_id in run requests."
+        ),
+        responses={
+            201: {
+                "description": "Session created successfully",
+                "content": {
+                    "application/json": {
+                        "examples": {
+                            "agent_session_example": {
+                                "summary": "Example created agent session",
+                                "value": {
+                                    "user_id": "user-123",
+                                    "agent_session_id": "new-session-id",
+                                    "session_id": "new-session-id",
+                                    "session_name": "New Session",
+                                    "session_state": {"key": "value"},
+                                    "metadata": {"key": "value"},
+                                    "agent_id": "agent-1",
+                                    "created_at": "2025-10-21T12:00:00Z",
+                                    "updated_at": "2025-10-21T12:00:00Z",
+                                },
+                            }
+                        }
+                    }
+                },
+            },
+            400: {"description": "Invalid request parameters", "model": BadRequestResponse},
+            422: {"description": "Validation error", "model": ValidationErrorResponse},
+            500: {"description": "Failed to create session", "model": InternalServerErrorResponse},
+        },
+    )
+    async def create_session(
+        request: Request,
+        session_type: SessionType = Query(
+            default=SessionType.AGENT, alias="type", description="Type of session to create (agent, team, or workflow)"
+        ),
+        create_session_request: CreateSessionRequest = Body(
+            default=CreateSessionRequest(), description="Session configuration data"
+        ),
+        db_id: Optional[str] = Query(default=None, description="Database ID to create session in"),
+    ) -> Union[AgentSessionDetailSchema, TeamSessionDetailSchema, WorkflowSessionDetailSchema]:
+        db = get_db(dbs, db_id)
+
+        # Get user_id from request state if available (from auth middleware)
+        user_id = create_session_request.user_id
+        if hasattr(request.state, "user_id"):
+            user_id = request.state.user_id
+
+        # Generate session_id if not provided
+        session_id = create_session_request.session_id or str(uuid4())
+
+        # Prepare session_data with session_state and session_name
+        session_data: dict[str, Any] = {}
+        if create_session_request.session_state is not None:
+            session_data["session_state"] = create_session_request.session_state
+        if create_session_request.session_name is not None:
+            session_data["session_name"] = create_session_request.session_name
+
+        current_time = int(time.time())
+
+        # Create the appropriate session type
+        session: Union[AgentSession, TeamSession, WorkflowSession]
+        if session_type == SessionType.AGENT:
+            session = AgentSession(
+                session_id=session_id,
+                agent_id=create_session_request.agent_id,
+                user_id=user_id,
+                session_data=session_data if session_data else None,
+                metadata=create_session_request.metadata,
+                created_at=current_time,
+                updated_at=current_time,
+            )
+        elif session_type == SessionType.TEAM:
+            session = TeamSession(
+                session_id=session_id,
+                team_id=create_session_request.team_id,
+                user_id=user_id,
+                session_data=session_data if session_data else None,
+                metadata=create_session_request.metadata,
+                created_at=current_time,
+                updated_at=current_time,
+            )
+        elif session_type == SessionType.WORKFLOW:
+            session = WorkflowSession(
+                session_id=session_id,
+                workflow_id=create_session_request.workflow_id,
+                user_id=user_id,
+                session_data=session_data if session_data else None,
+                metadata=create_session_request.metadata,
+                created_at=current_time,
+                updated_at=current_time,
+            )
+        else:
+            raise HTTPException(status_code=400, detail=f"Invalid session type: {session_type}")
+
+        # Upsert the session to the database
+        try:
+            if isinstance(db, AsyncBaseDb):
+                db = cast(AsyncBaseDb, db)
+                created_session = await db.upsert_session(session, deserialize=True)
+            else:
+                created_session = db.upsert_session(session, deserialize=True)
+
+            if not created_session:
+                raise HTTPException(status_code=500, detail="Failed to create session")
+
+            # Return appropriate schema based on session type
+            if session_type == SessionType.AGENT:
+                return AgentSessionDetailSchema.from_session(created_session)  # type: ignore
+            elif session_type == SessionType.TEAM:
+                return TeamSessionDetailSchema.from_session(created_session)  # type: ignore
+            else:
+                return WorkflowSessionDetailSchema.from_session(created_session)  # type: ignore
+        except Exception as e:
+            logger.error(f"Error creating session: {e}")
+            raise HTTPException(status_code=500, detail=f"Failed to create session: {str(e)}")
+
     @router.get(
         "/sessions/{session_id}",
         response_model=Union[AgentSessionDetailSchema, TeamSessionDetailSchema, WorkflowSessionDetailSchema],
@@ -271,8 +403,9 @@ def attach_routes(router: APIRouter, dbs: dict[str, Union[BaseDb, AsyncBaseDb]])
         operation_id="get_session_runs",
         summary="Get Session Runs",
         description=(
-            "Retrieve all runs (executions) for a specific session. Runs represent individual "
-            "interactions or executions within a session. Response schema varies based on session type."
+            "Retrieve all runs (executions) for a specific session with optional timestamp filtering. "
+            "Runs represent individual interactions or executions within a session. "
+            "Response schema varies based on session type."
         ),
         responses={
             200: {
@@ -386,6 +519,14 @@ def attach_routes(router: APIRouter, dbs: dict[str, Union[BaseDb, AsyncBaseDb]])
             default=SessionType.AGENT, description="Session type (agent, team, or workflow)", alias="type"
         ),
         user_id: Optional[str] = Query(default=None, description="User ID to query runs from"),
+        created_after: Optional[int] = Query(
+            default=None,
+            description="Filter runs created after this Unix timestamp (epoch time in seconds)",
+        ),
+        created_before: Optional[int] = Query(
+            default=None,
+            description="Filter runs created before this Unix timestamp (epoch time in seconds)",
+        ),
         db_id: Optional[str] = Query(default=None, description="Database ID to query runs from"),
     ) -> List[Union[RunSchema, TeamRunSchema, WorkflowRunSchema]]:
         db = get_db(dbs, db_id)
@@ -393,6 +534,10 @@ def attach_routes(router: APIRouter, dbs: dict[str, Union[BaseDb, AsyncBaseDb]])
         if hasattr(request.state, "user_id"):
             user_id = request.state.user_id
 
+        # Use timestamp filters directly (already in epoch format)
+        start_timestamp = created_after
+        end_timestamp = created_before
+
         if isinstance(db, AsyncBaseDb):
             db = cast(AsyncBaseDb, db)
             session = await db.get_session(
@@ -408,15 +553,33 @@ def attach_routes(router: APIRouter, dbs: dict[str, Union[BaseDb, AsyncBaseDb]])
 
         runs = session.get("runs")  # type: ignore
         if not runs:
-            raise HTTPException(status_code=404, detail=f"Session with ID {session_id} has no runs")
+            return []
+
+        # Filter runs by timestamp if specified
+        # TODO: Move this filtering into the DB layer
+        filtered_runs = []
+        for run in runs:
+            if start_timestamp or end_timestamp:
+                run_created_at = run.get("created_at")
+                if run_created_at:
+                    # created_at is stored as epoch int
+                    if start_timestamp and run_created_at < start_timestamp:
+                        continue
+                    if end_timestamp and run_created_at > end_timestamp:
+                        continue
+
+            filtered_runs.append(run)
+
+        if not filtered_runs:
+            return []
 
         run_responses: List[Union[RunSchema, TeamRunSchema, WorkflowRunSchema]] = []
 
         if session_type == SessionType.AGENT:
-            return [RunSchema.from_dict(run) for run in runs]
+            return [RunSchema.from_dict(run) for run in filtered_runs]
 
         elif session_type == SessionType.TEAM:
-            for run in runs:
+            for run in filtered_runs:
                 if run.get("agent_id") is not None:
                     run_responses.append(RunSchema.from_dict(run))
                 elif run.get("team_id") is not None:
@@ -424,7 +587,7 @@ def attach_routes(router: APIRouter, dbs: dict[str, Union[BaseDb, AsyncBaseDb]])
             return run_responses
 
         elif session_type == SessionType.WORKFLOW:
-            for run in runs:
+            for run in filtered_runs:
                 if run.get("workflow_id") is not None:
                     run_responses.append(WorkflowRunSchema.from_dict(run))
                 elif run.get("team_id") is not None:
@@ -435,6 +598,93 @@ def attach_routes(router: APIRouter, dbs: dict[str, Union[BaseDb, AsyncBaseDb]])
         else:
             raise HTTPException(status_code=400, detail=f"Invalid session type: {session_type}")
 
+    @router.get(
+        "/sessions/{session_id}/runs/{run_id}",
+        response_model=Union[RunSchema, TeamRunSchema, WorkflowRunSchema],
+        status_code=200,
+        operation_id="get_session_run",
+        summary="Get Run by ID",
+        description=(
+            "Retrieve a specific run by its ID from a session. Response schema varies based on the "
+            "run type (agent run, team run, or workflow run)."
+        ),
+        responses={
+            200: {
+                "description": "Run retrieved successfully",
+                "content": {
+                    "application/json": {
+                        "examples": {
+                            "agent_run": {
+                                "summary": "Example agent run",
+                                "value": {
+                                    "run_id": "fcdf50f0-7c32-4593-b2ef-68a558774340",
+                                    "parent_run_id": "80056af0-c7a5-4d69-b6a2-c3eba9f040e0",
+                                    "agent_id": "basic-agent",
+                                    "user_id": "user_123",
+                                    "run_input": "Which tools do you have access to?",
+                                    "content": "I don't have access to external tools.",
+                                    "created_at": 1728499200,
+                                },
+                            }
+                        }
+                    }
+                },
+            },
+            404: {"description": "Session or run not found", "model": NotFoundResponse},
+            422: {"description": "Invalid session type", "model": ValidationErrorResponse},
+        },
+    )
+    async def get_session_run(
+        request: Request,
+        session_id: str = Path(description="Session ID to get run from"),
+        run_id: str = Path(description="Run ID to retrieve"),
+        session_type: SessionType = Query(
+            default=SessionType.AGENT, description="Session type (agent, team, or workflow)", alias="type"
+        ),
+        user_id: Optional[str] = Query(default=None, description="User ID to query run from"),
+        db_id: Optional[str] = Query(default=None, description="Database ID to query run from"),
+    ) -> Union[RunSchema, TeamRunSchema, WorkflowRunSchema]:
+        db = get_db(dbs, db_id)
+
+        if hasattr(request.state, "user_id"):
+            user_id = request.state.user_id
+
+        if isinstance(db, AsyncBaseDb):
+            db = cast(AsyncBaseDb, db)
+            session = await db.get_session(
+                session_id=session_id, session_type=session_type, user_id=user_id, deserialize=False
+            )
+        else:
+            session = db.get_session(
+                session_id=session_id, session_type=session_type, user_id=user_id, deserialize=False
+            )
+
+        if not session:
+            raise HTTPException(status_code=404, detail=f"Session with ID {session_id} not found")
+
+        runs = session.get("runs")  # type: ignore
+        if not runs:
+            raise HTTPException(status_code=404, detail=f"Session with ID {session_id} has no runs")
+
+        # Find the specific run
+        # TODO: Move this filtering into the DB layer
+        target_run = None
+        for run in runs:
+            if run.get("run_id") == run_id:
+                target_run = run
+                break
+
+        if not target_run:
+            raise HTTPException(status_code=404, detail=f"Run with ID {run_id} not found in session {session_id}")
+
+        # Return the appropriate schema based on run type
+        if target_run.get("workflow_id") is not None:
+            return WorkflowRunSchema.from_dict(target_run)
+        elif target_run.get("team_id") is not None:
+            return TeamRunSchema.from_dict(target_run)
+        else:
+            return RunSchema.from_dict(target_run)
+
     @router.delete(
         "/sessions/{session_id}",
         status_code=204,
@@ -609,4 +859,129 @@ def attach_routes(router: APIRouter, dbs: dict[str, Union[BaseDb, AsyncBaseDb]])
         else:
             return WorkflowSessionDetailSchema.from_session(session)  # type: ignore
 
+    @router.patch(
+        "/sessions/{session_id}",
+        response_model=Union[AgentSessionDetailSchema, TeamSessionDetailSchema, WorkflowSessionDetailSchema],
+        status_code=200,
+        operation_id="update_session",
+        summary="Update Session",
+        description=(
+            "Update session properties such as session_name, session_state, metadata, or summary. "
+            "Use this endpoint to modify the session name, update state, add metadata, or update the session summary."
+        ),
+        responses={
+            200: {
+                "description": "Session updated successfully",
+                "content": {
+                    "application/json": {
+                        "examples": {
+                            "update_summary": {
+                                "summary": "Update session summary",
+                                "value": {
+                                    "summary": {
+                                        "summary": "The user discussed project planning with the agent.",
+                                        "updated_at": "2025-10-21T14:30:00Z",
+                                    }
+                                },
+                            },
+                            "update_metadata": {
+                                "summary": "Update session metadata",
+                                "value": {
+                                    "metadata": {
+                                        "tags": ["planning", "project"],
+                                        "priority": "high",
+                                    }
+                                },
+                            },
+                            "update_session_name": {
+                                "summary": "Update session name",
+                                "value": {"session_name": "Updated Session Name"},
+                            },
+                            "update_session_state": {
+                                "summary": "Update session state",
+                                "value": {
+                                    "session_state": {
+                                        "step": "completed",
+                                        "context": "Project planning finished",
+                                        "progress": 100,
+                                    }
+                                },
+                            },
+                        }
+                    }
+                },
+            },
+            404: {"description": "Session not found", "model": NotFoundResponse},
+            422: {"description": "Invalid request", "model": ValidationErrorResponse},
+            500: {"description": "Failed to update session", "model": InternalServerErrorResponse},
+        },
+    )
+    async def update_session(
+        request: Request,
+        session_id: str = Path(description="Session ID to update"),
+        session_type: SessionType = Query(
+            default=SessionType.AGENT, description="Session type (agent, team, or workflow)", alias="type"
+        ),
+        update_data: UpdateSessionRequest = Body(description="Session update data"),
+        user_id: Optional[str] = Query(default=None, description="User ID"),
+        db_id: Optional[str] = Query(default=None, description="Database ID to use for update operation"),
+    ) -> Union[AgentSessionDetailSchema, TeamSessionDetailSchema, WorkflowSessionDetailSchema]:
+        db = get_db(dbs, db_id)
+
+        if hasattr(request.state, "user_id"):
+            user_id = request.state.user_id
+
+        # Get the existing session
+        if isinstance(db, AsyncBaseDb):
+            db = cast(AsyncBaseDb, db)
+            existing_session = await db.get_session(
+                session_id=session_id, session_type=session_type, user_id=user_id, deserialize=True
+            )
+        else:
+            existing_session = db.get_session(
+                session_id=session_id, session_type=session_type, user_id=user_id, deserialize=True
+            )
+
+        if not existing_session:
+            raise HTTPException(status_code=404, detail=f"Session with id '{session_id}' not found")
+
+        # Update session properties
+        # Handle session_name - stored in session_data
+        if update_data.session_name is not None:
+            if existing_session.session_data is None:  # type: ignore
+                existing_session.session_data = {}  # type: ignore
+            existing_session.session_data["session_name"] = update_data.session_name  # type: ignore
+
+        # Handle session_state - stored in session_data
+        if update_data.session_state is not None:
+            if existing_session.session_data is None:  # type: ignore
+                existing_session.session_data = {}  # type: ignore
+            existing_session.session_data["session_state"] = update_data.session_state  # type: ignore
+
+        if update_data.metadata is not None:
+            existing_session.metadata = update_data.metadata  # type: ignore
+
+        if update_data.summary is not None:
+            from agno.session.summary import SessionSummary
+
+            existing_session.summary = SessionSummary.from_dict(update_data.summary)  # type: ignore
+
+        # Upsert the updated session
+        if isinstance(db, AsyncBaseDb):
+            db = cast(AsyncBaseDb, db)
+            updated_session = await db.upsert_session(existing_session, deserialize=True)  # type: ignore
+        else:
+            updated_session = db.upsert_session(existing_session, deserialize=True)  # type: ignore
+
+        if not updated_session:
+            raise HTTPException(status_code=500, detail="Failed to update session")
+
+        # Return appropriate schema based on session type
+        if session_type == SessionType.AGENT:
+            return AgentSessionDetailSchema.from_session(updated_session)  # type: ignore
+        elif session_type == SessionType.TEAM:
+            return TeamSessionDetailSchema.from_session(updated_session)  # type: ignore
+        else:
+            return WorkflowSessionDetailSchema.from_session(updated_session)  # type: ignore
+
     return router