remdb 0.3.0__py3-none-any.whl → 0.3.114__py3-none-any.whl

rem/api/routers/dev.py

@@ -0,0 +1,81 @@
+"""
+Development utilities router (non-production only).
+
+Provides testing endpoints that are available in development/staging environments
+regardless of auth configuration. These endpoints are NEVER available in production.
+
+Endpoints:
+- GET  /api/dev/token    - Get a dev token for test-user
+"""
+
+from fastapi import APIRouter, HTTPException, Request
+from loguru import logger
+
+from ...settings import settings
+
+router = APIRouter(prefix="/api/dev", tags=["dev"])
+
+
+def generate_dev_token() -> str:
+    """
+    Generate a dev token for testing.
+
+    Token format: dev_<hmac_signature>
+    The signature is based on the session secret to ensure only valid tokens work.
+    """
+    import hashlib
+    import hmac
+
+    # Use session secret as key
+    secret = settings.auth.session_secret or "dev-secret"
+    message = "test-user:dev-token"
+
+    signature = hmac.new(
+        secret.encode(),
+        message.encode(),
+        hashlib.sha256
+    ).hexdigest()[:32]
+
+    return f"dev_{signature}"
+
+
+def verify_dev_token(token: str) -> bool:
+    """Verify a dev token is valid."""
+    expected = generate_dev_token()
+    return token == expected
+
+
+@router.get("/token")
+async def get_dev_token(request: Request):
+    """
+    Get a development token for testing (non-production only).
+
+    This token can be used as a Bearer token to authenticate as the
+    test user (test-user / test@rem.local) without going through OAuth.
+
+    Usage:
+        curl -H "Authorization: Bearer <token>" http://localhost:8000/api/v1/...
+
+    Returns:
+        401 if in production environment
+        Token and usage instructions otherwise
+    """
+    if settings.environment == "production":
+        raise HTTPException(
+            status_code=401,
+            detail="Dev tokens are not available in production"
+        )
+
+    token = generate_dev_token()
+
+    return {
+        "token": token,
+        "type": "Bearer",
+        "user": {
+            "id": "test-user",
+            "email": "test@rem.local",
+            "name": "Test User",
+        },
+        "usage": f'curl -H "Authorization: Bearer {token}" http://localhost:8000/api/v1/...',
+        "warning": "This token is for development/testing only and will not work in production.",
+    }

rem/api/routers/feedback.py

@@ -0,0 +1,148 @@
+"""
+Message feedback endpoint.
+
+Provides endpoint for submitting feedback on messages.
+
+Endpoints:
+    POST /api/v1/messages/feedback - Submit feedback on a message
+
+Trace Integration:
+- Feedback can reference trace_id/span_id for OTEL integration
+- Phoenix sync attaches feedback as span annotations (async)
+"""
+
+from fastapi import APIRouter, Header, HTTPException, Request
+from loguru import logger
+from pydantic import BaseModel, Field
+
+from ..deps import get_user_id_from_request
+from ...models.entities import Feedback, Message
+from ...services.postgres import Repository
+from ...settings import settings
+
+router = APIRouter(prefix="/api/v1", tags=["messages"])
+
+
+# =============================================================================
+# Request/Response Models
+# =============================================================================
+
+
+class FeedbackCreateRequest(BaseModel):
+    """Request to submit feedback."""
+
+    session_id: str = Field(description="Session ID this feedback relates to")
+    message_id: str | None = Field(
+        default=None, description="Specific message ID (null for session-level)"
+    )
+    rating: int | None = Field(
+        default=None,
+        ge=-1,
+        le=5,
+        description="Rating: -1 (thumbs down), 1 (thumbs up), or 1-5 scale",
+    )
+    categories: list[str] = Field(
+        default_factory=list, description="Feedback categories"
+    )
+    comment: str | None = Field(default=None, description="Free-text comment")
+    trace_id: str | None = Field(
+        default=None, description="OTEL trace ID (auto-resolved if message has it)"
+    )
+    span_id: str | None = Field(
+        default=None, description="OTEL span ID (auto-resolved if message has it)"
+    )
+
+
+class FeedbackResponse(BaseModel):
+    """Response after submitting feedback."""
+
+    id: str
+    session_id: str
+    message_id: str | None
+    rating: int | None
+    categories: list[str]
+    comment: str | None
+    trace_id: str | None
+    span_id: str | None
+    phoenix_synced: bool
+    created_at: str
+
+
+# =============================================================================
+# Feedback Endpoint
+# =============================================================================
+
+
+@router.post("/messages/feedback", response_model=FeedbackResponse, status_code=201)
+async def submit_feedback(
+    request: Request,
+    request_body: FeedbackCreateRequest,
+    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
+) -> FeedbackResponse:
+    """
+    Submit feedback on a message or session.
+
+    If message_id is provided, feedback is attached to that specific message.
+    If only session_id is provided, feedback applies to the entire session.
+
+    Trace IDs (trace_id, span_id) can be:
+    - Provided explicitly in the request
+    - Auto-resolved from the message if message_id is provided
+
+    Returns:
+        Created feedback object
+    """
+    if not settings.postgres.enabled:
+        raise HTTPException(status_code=503, detail="Database not enabled")
+
+    effective_user_id = get_user_id_from_request(request)
+
+    # Resolve trace_id/span_id from message if not provided
+    trace_id = request_body.trace_id
+    span_id = request_body.span_id
+
+    if request_body.message_id and (not trace_id or not span_id):
+        message_repo = Repository(Message, table_name="messages")
+        message = await message_repo.get_by_id(request_body.message_id, x_tenant_id)
+        if message:
+            trace_id = trace_id or message.trace_id
+            span_id = span_id or message.span_id
+
+    feedback = Feedback(
+        session_id=request_body.session_id,
+        message_id=request_body.message_id,
+        rating=request_body.rating,
+        categories=request_body.categories,
+        comment=request_body.comment,
+        trace_id=trace_id,
+        span_id=span_id,
+        phoenix_synced=False,
+        annotator_kind="HUMAN",
+        user_id=effective_user_id,
+        tenant_id=x_tenant_id,
+    )
+
+    repo = Repository(Feedback, table_name="feedbacks")
+    result = await repo.upsert(feedback)
+
+    logger.info(
+        f"Feedback submitted: session={request_body.session_id}, "
+        f"message={request_body.message_id}, rating={request_body.rating}"
+    )
+
+    # TODO: Async sync to Phoenix if trace_id/span_id available
+    if trace_id and span_id:
+        logger.debug(f"Feedback has trace info: trace={trace_id}, span={span_id}")
+
+    return FeedbackResponse(
+        id=str(result.id),
+        session_id=result.session_id,
+        message_id=result.message_id,
+        rating=result.rating,
+        categories=result.categories,
+        comment=result.comment,
+        trace_id=result.trace_id,
+        span_id=result.span_id,
+        phoenix_synced=result.phoenix_synced,
+        created_at=result.created_at.isoformat() if result.created_at else "",
+    )

rem/api/routers/messages.py

@@ -0,0 +1,473 @@
+"""
+Messages and Sessions endpoints.
+
+Provides endpoints for:
+- Listing and filtering messages by date, user_id, session_id
+- Creating and managing sessions (normal or evaluation mode)
+
+Endpoints:
+    GET  /api/v1/messages           - List messages with filters
+    GET  /api/v1/messages/{id}      - Get a specific message
+
+    GET  /api/v1/sessions           - List sessions
+    POST /api/v1/sessions           - Create a session
+    GET  /api/v1/sessions/{id}      - Get a specific session
+    PUT  /api/v1/sessions/{id}      - Update a session
+"""
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Header, HTTPException, Query, Request
+from loguru import logger
+from pydantic import BaseModel, Field
+
+from ..deps import (
+    get_current_user,
+    get_user_filter,
+    is_admin,
+    require_admin,
+    require_auth,
+)
+from ...models.entities import Message, Session, SessionMode
+from ...services.postgres import Repository, get_postgres_service
+from ...settings import settings
+from ...utils.date_utils import parse_iso, utc_now
+
+router = APIRouter(prefix="/api/v1")
+
+
+# =============================================================================
+# Request/Response Models
+# =============================================================================
+
+
+class MessageListResponse(BaseModel):
+    """Response for message list endpoint."""
+
+    object: Literal["list"] = "list"
+    data: list[Message]
+    total: int
+    has_more: bool
+
+
+class SessionCreateRequest(BaseModel):
+    """Request to create a new session."""
+
+    name: str = Field(description="Session name/identifier")
+    mode: SessionMode = Field(
+        default=SessionMode.NORMAL, description="Session mode: 'normal' or 'evaluation'"
+    )
+    description: str | None = Field(default=None, description="Session description")
+    original_trace_id: str | None = Field(
+        default=None,
+        description="For evaluation: ID of the original session being evaluated",
+    )
+    settings_overrides: dict | None = Field(
+        default=None,
+        description="Settings overrides (model, temperature, max_tokens, system_prompt)",
+    )
+    prompt: str | None = Field(default=None, description="Custom prompt for this session")
+    agent_schema_uri: str | None = Field(
+        default=None, description="Agent schema URI for this session"
+    )
+
+
+class SessionUpdateRequest(BaseModel):
+    """Request to update a session."""
+
+    description: str | None = None
+    settings_overrides: dict | None = None
+    prompt: str | None = None
+    message_count: int | None = None
+    total_tokens: int | None = None
+
+
+class SessionListResponse(BaseModel):
+    """Response for session list endpoint (deprecated, use SessionsQueryResponse)."""
+
+    object: Literal["list"] = "list"
+    data: list[Session]
+    total: int
+    has_more: bool
+
+
+class PaginationMetadata(BaseModel):
+    """Pagination metadata for paginated responses."""
+
+    total: int = Field(description="Total number of records matching filters")
+    page: int = Field(description="Current page number (1-indexed)")
+    page_size: int = Field(description="Number of records per page")
+    total_pages: int = Field(description="Total number of pages")
+    has_next: bool = Field(description="Whether there are more pages after this one")
+    has_previous: bool = Field(description="Whether there are pages before this one")
+
+
+class SessionsQueryResponse(BaseModel):
+    """Response for paginated sessions query."""
+
+    object: Literal["list"] = "list"
+    data: list[Session] = Field(description="List of sessions for the current page")
+    metadata: PaginationMetadata = Field(description="Pagination metadata")
+
+
+# =============================================================================
+# Messages Endpoints
+# =============================================================================
+
+
+@router.get("/messages", response_model=MessageListResponse, tags=["messages"])
+async def list_messages(
+    request: Request,
+    mine: bool = Query(default=False, description="Only show my messages (uses JWT identity)"),
+    user_id: str | None = Query(default=None, description="Filter by user ID (admin only for cross-user)"),
+    session_id: str | None = Query(default=None, description="Filter by session ID"),
+    start_date: str | None = Query(
+        default=None, description="Filter messages after this ISO date"
+    ),
+    end_date: str | None = Query(
+        default=None, description="Filter messages before this ISO date"
+    ),
+    message_type: str | None = Query(
+        default=None, description="Filter by message type (user, assistant, system, tool)"
+    ),
+    limit: int = Query(default=50, ge=1, le=100, description="Max results to return"),
+    offset: int = Query(default=0, ge=0, description="Offset for pagination"),
+    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
+) -> MessageListResponse:
+    """
+    List messages with optional filters.
+
+    Access Control:
+    - Regular users: Only see their own messages
+    - Admin users: Can filter by any user_id or see all messages
+    - mine=true: Forces filter to current user (useful for admins to see only their own)
+
+    Filters can be combined:
+    - mine: Only show messages owned by current JWT user (overrides user_id)
+    - user_id: Filter by the user who created/owns the message (admin only for cross-user)
+    - session_id: Filter by conversation session
+    - start_date/end_date: Filter by creation time range (ISO 8601 format)
+    - message_type: Filter by role (user, assistant, system, tool)
+
+    Returns paginated results ordered by created_at descending.
+    """
+    if not settings.postgres.enabled:
+        raise HTTPException(status_code=503, detail="Database not enabled")
+
+    repo = Repository(Message, table_name="messages")
+
+    # If mine=true, force filter to current user's ID from JWT
+    effective_user_id = user_id
+    if mine:
+        current_user = get_current_user(request)
+        if current_user:
+            effective_user_id = current_user.get("id")
+
+    # Build user-scoped filters (admin can see all, regular users see only their own)
+    filters = await get_user_filter(request, x_user_id=effective_user_id, x_tenant_id=x_tenant_id)
+
+    # Apply optional filters
+    if session_id:
+        filters["session_id"] = session_id
+    if message_type:
+        filters["message_type"] = message_type
+
+    # For date filtering, we need custom SQL (not supported by basic Repository)
+    # For now, fetch all matching base filters and filter in Python
+    # TODO: Extend Repository to support date range filters
+    messages = await repo.find(
+        filters,
+        order_by="created_at DESC",
+        limit=limit + 1,  # Fetch one extra to determine has_more
+        offset=offset,
+    )
+
+    # Apply date filters in Python if provided
+    if start_date or end_date:
+        start_dt = parse_iso(start_date) if start_date else None
+        end_dt = parse_iso(end_date) if end_date else None
+
+        filtered = []
+        for msg in messages:
+            if start_dt and msg.created_at < start_dt:
+                continue
+            if end_dt and msg.created_at > end_dt:
+                continue
+            filtered.append(msg)
+        messages = filtered
+
+    # Determine if there are more results
+    has_more = len(messages) > limit
+    if has_more:
+        messages = messages[:limit]
+
+    # Get total count for pagination info
+    total = await repo.count(filters)
+
+    return MessageListResponse(data=messages, total=total, has_more=has_more)
+
+
+@router.get("/messages/{message_id}", response_model=Message, tags=["messages"])
+async def get_message(
+    request: Request,
+    message_id: str,
+    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
+) -> Message:
+    """
+    Get a specific message by ID.
+
+    Access Control:
+    - Regular users: Only access their own messages
+    - Admin users: Can access any message
+
+    Args:
+        message_id: UUID of the message
+
+    Returns:
+        Message object if found
+
+    Raises:
+        404: Message not found
+        403: Access denied (not owner and not admin)
+    """
+    if not settings.postgres.enabled:
+        raise HTTPException(status_code=503, detail="Database not enabled")
+
+    repo = Repository(Message, table_name="messages")
+    message = await repo.get_by_id(message_id, x_tenant_id)
+
+    if not message:
+        raise HTTPException(status_code=404, detail=f"Message '{message_id}' not found")
+
+    # Check access: admin or owner
+    current_user = get_current_user(request)
+    if not is_admin(current_user):
+        user_id = current_user.get("id") if current_user else None
+        if message.user_id and message.user_id != user_id:
+            raise HTTPException(status_code=403, detail="Access denied: not owner")
+
+    return message
+
+
+# =============================================================================
+# Sessions Endpoints
+# =============================================================================
+
+
+@router.get("/sessions", response_model=SessionsQueryResponse, tags=["sessions"])
+async def list_sessions(
+    request: Request,
+    user_id: str | None = Query(default=None, description="Filter by user ID (admin only for cross-user)"),
+    mode: SessionMode | None = Query(default=None, description="Filter by session mode"),
+    page: int = Query(default=1, ge=1, description="Page number (1-indexed)"),
+    page_size: int = Query(default=50, ge=1, le=100, description="Number of results per page"),
+    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
+) -> SessionsQueryResponse:
+    """
+    List sessions with optional filters and page-based pagination.
+
+    Access Control:
+    - Regular users: Only see their own sessions
+    - Admin users: Can filter by any user_id or see all sessions
+
+    Filters:
+    - user_id: Filter by session owner (admin only for cross-user)
+    - mode: Filter by session mode (normal or evaluation)
+
+    Pagination:
+    - page: Page number (1-indexed, default: 1)
+    - page_size: Number of sessions per page (default: 50, max: 100)
+
+    Returns paginated results ordered by created_at descending with pagination metadata.
+    """
+    if not settings.postgres.enabled:
+        raise HTTPException(status_code=503, detail="Database not enabled")
+
+    repo = Repository(Session, table_name="sessions")
+
+    # Build user-scoped filters (admin can see all, regular users see only their own)
+    filters = await get_user_filter(request, x_user_id=user_id, x_tenant_id=x_tenant_id)
+    if mode:
+        filters["mode"] = mode.value
+
+    # Use CTE-based pagination with ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY created_at DESC)
+    result = await repo.find_paginated(
+        filters,
+        page=page,
+        page_size=page_size,
+        order_by="created_at DESC",
+        partition_by="user_id",
+    )
+
+    return SessionsQueryResponse(
+        data=result["data"],
+        metadata=PaginationMetadata(
+            total=result["total"],
+            page=result["page"],
+            page_size=result["page_size"],
+            total_pages=result["total_pages"],
+            has_next=result["has_next"],
+            has_previous=result["has_previous"],
+        ),
+    )
+
+
+@router.post("/sessions", response_model=Session, status_code=201, tags=["sessions"])
+async def create_session(
+    request_body: SessionCreateRequest,
+    user: dict = Depends(require_admin),
+    x_user_id: str = Header(alias="X-User-Id", default="default"),
+    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
+) -> Session:
+    """
+    Create a new session.
+
+    **Requires admin role.**
+
+    For normal sessions, only name is required.
+    For evaluation sessions, you can specify:
+    - original_trace_id: The session being re-evaluated
+    - settings_overrides: Model, temperature, prompt overrides
+    - prompt: Custom prompt to test
+
+    Headers:
+    - X-User-Id: User identifier (owner of the session)
+    - X-Tenant-Id: Tenant identifier
+
+    Returns:
+        Created session object
+    """
+    if not settings.postgres.enabled:
+        raise HTTPException(status_code=503, detail="Database not enabled")
+
+    # Admin can specify x_user_id, or default to their own
+    effective_user_id = x_user_id if x_user_id != "default" else user.get("id", "default")
+
+    session = Session(
+        name=request_body.name,
+        mode=request_body.mode,
+        description=request_body.description,
+        original_trace_id=request_body.original_trace_id,
+        settings_overrides=request_body.settings_overrides,
+        prompt=request_body.prompt,
+        agent_schema_uri=request_body.agent_schema_uri,
+        user_id=effective_user_id,
+        tenant_id=x_tenant_id,
+    )
+
+    repo = Repository(Session, table_name="sessions")
+    result = await repo.upsert(session)
+
+    logger.info(
+        f"Admin {user.get('email')} created session '{session.name}' "
+        f"(mode={session.mode}) for user={effective_user_id}"
+    )
+
+    return result  # type: ignore
+
+
+@router.get("/sessions/{session_id}", response_model=Session, tags=["sessions"])
+async def get_session(
+    request: Request,
+    session_id: str,
+    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
+) -> Session:
+    """
+    Get a specific session by ID.
+
+    Access Control:
+    - Regular users: Only access their own sessions
+    - Admin users: Can access any session
+
+    Args:
+        session_id: UUID or name of the session
+
+    Returns:
+        Session object if found
+
+    Raises:
+        404: Session not found
+        403: Access denied (not owner and not admin)
+    """
+    if not settings.postgres.enabled:
+        raise HTTPException(status_code=503, detail="Database not enabled")
+
+    repo = Repository(Session, table_name="sessions")
+    session = await repo.get_by_id(session_id, x_tenant_id)
+
+    if not session:
+        # Try finding by name
+        sessions = await repo.find({"name": session_id, "tenant_id": x_tenant_id}, limit=1)
+        if sessions:
+            session = sessions[0]
+        else:
+            raise HTTPException(status_code=404, detail=f"Session '{session_id}' not found")
+
+    # Check access: admin or owner
+    current_user = get_current_user(request)
+    if not is_admin(current_user):
+        user_id = current_user.get("id") if current_user else None
+        if session.user_id and session.user_id != user_id:
+            raise HTTPException(status_code=403, detail="Access denied: not owner")
+
+    return session
+
+
+@router.put("/sessions/{session_id}", response_model=Session, tags=["sessions"])
+async def update_session(
+    request: Request,
+    session_id: str,
+    request_body: SessionUpdateRequest,
+    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
+) -> Session:
+    """
+    Update an existing session.
+
+    Access Control:
+    - Regular users: Only update their own sessions
+    - Admin users: Can update any session
+
+    Allows updating:
+    - description
+    - settings_overrides
+    - prompt
+    - message_count (typically updated automatically)
+    - total_tokens (typically updated automatically)
+
+    Args:
+        session_id: UUID of the session
+
+    Returns:
+        Updated session object
+
+    Raises:
+        404: Session not found
+        403: Access denied (not owner and not admin)
+    """
+    if not settings.postgres.enabled:
+        raise HTTPException(status_code=503, detail="Database not enabled")
+
+    repo = Repository(Session, table_name="sessions")
+    session = await repo.get_by_id(session_id, x_tenant_id)
+
+    if not session:
+        raise HTTPException(status_code=404, detail=f"Session '{session_id}' not found")
+
+    # Check access: admin or owner
+    current_user = get_current_user(request)
+    if not is_admin(current_user):
+        user_id = current_user.get("id") if current_user else None
+        if session.user_id and session.user_id != user_id:
+            raise HTTPException(status_code=403, detail="Access denied: not owner")
+
+    # Apply updates
+    update_data = request_body.model_dump(exclude_none=True)
+    for field, value in update_data.items():
+        setattr(session, field, value)
+
+    session.updated_at = utc_now()
+
+    result = await repo.update(session)
+    return result