session page support ui & backend

Author: shirleyai-co

backend/rest/main.py

@@ -18,6 +18,7 @@
 
 from rest.routers.internal import router as internal_router
 from rest.routers.public.traces import router as public_traces_router
+from rest.routers.sessions import router as sessions_router
 from rest.routers.traces import router as traces_router
 from rest.routers.users import router as users_router
 from rest.schemas.common import HealthResponse
@@ -41,6 +42,7 @@
 # Trace reading from ClickHouse (user auth via headers from Next.js)
 app.include_router(traces_router, prefix="/api/v1")
 app.include_router(users_router, prefix="/api/v1")
+app.include_router(sessions_router, prefix="/api/v1")
 
 # Public API for SDK ingestion (API key auth)
 app.include_router(public_traces_router, prefix="/api/v1")

backend/rest/routers/sessions.py

@@ -0,0 +1,70 @@
+"""Session query endpoints (user-authenticated, not public API)."""
+
+import logging
+from datetime import datetime
+
+from fastapi import APIRouter, HTTPException, Query, status
+
+from rest.routers.deps import ProjectAccess
+from rest.schemas.sessions import SessionDetailResponse, SessionListResponse
+from rest.services.trace_reader import get_trace_reader_service
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/projects/{project_id}/sessions", tags=["Sessions"])
+
+
+@router.get("", response_model=SessionListResponse)
+async def list_sessions(
+    project_id: str,
+    _access: ProjectAccess,
+    page: int = Query(0, ge=0, description="Page number (0-indexed)"),
+    limit: int = Query(50, ge=1, le=200, description="Items per page"),
+    search_query: str | None = Query(None, description="Search by session_id"),
+    start_after: datetime | None = Query(None, description="Filter traces after this time"),
+    end_before: datetime | None = Query(None, description="Filter traces before this time"),
+):
+    """List unique sessions for a project with trace counts and token totals."""
+    try:
+        service = get_trace_reader_service()
+        result = service.list_sessions(
+            project_id=project_id,
+            page=page,
+            limit=limit,
+            search_query=search_query,
+            start_after=start_after,
+            end_before=end_before,
+        )
+        return result
+    except Exception as e:
+        logger.exception(f"Error listing sessions: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to list sessions",
+        ) from e
+
+
+@router.get("/{session_id}", response_model=SessionDetailResponse)
+async def get_session(
+    project_id: str,
+    session_id: str,
+    _access: ProjectAccess,
+):
+    """Get session detail with all traces for conversation view."""
+    try:
+        service = get_trace_reader_service()
+        result = service.get_session(project_id=project_id, session_id=session_id)
+        if result is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Session not found",
+            )
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception(f"Error getting session: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to get session",
+        ) from e

backend/rest/schemas/sessions.py

@@ -0,0 +1,56 @@
+"""Session-related response schemas."""
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+from rest.schemas.common import PaginationMeta
+
+
+class SessionListItem(BaseModel):
+    """Single session with aggregated trace statistics."""
+
+    session_id: str
+    trace_count: int
+    user_ids: list[str]
+    first_trace_time: datetime | None
+    last_trace_time: datetime | None
+    duration_ms: float | None
+    total_input_tokens: int | None
+    total_output_tokens: int | None
+    input: str | None
+    output: str | None
+
+
+class SessionListResponse(BaseModel):
+    """Paginated list of sessions."""
+
+    data: list[SessionListItem]
+    meta: PaginationMeta
+
+
+class SessionTraceItem(BaseModel):
+    """Single trace within a session, for conversation view."""
+
+    trace_id: str
+    name: str
+    trace_start_time: datetime
+    user_id: str | None
+    input: str | None
+    output: str | None
+    duration_ms: float | None
+    status: str
+
+
+class SessionDetailResponse(BaseModel):
+    """Session detail with all traces for conversation view."""
+
+    session_id: str
+    traces: list[SessionTraceItem]
+    user_ids: list[str]
+    trace_count: int
+    first_trace_time: datetime | None
+    last_trace_time: datetime | None
+    duration_ms: float | None
+    total_input_tokens: int | None
+    total_output_tokens: int | None