app/api/v2/recommendations.py

"""Recommendations API router.

Exposes GET /ai/v2/recommendations/{student_id} for content recommendations.
"""

from fastapi import APIRouter, Depends, Query

from app.api.v2.dependencies import get_recommendation_service
from app.schemas.recommendations import RecommendationResponse

router = APIRouter(prefix="/ai/v2", tags=["inference"])


@router.get(
    "/recommendations/{student_id}",
    response_model=RecommendationResponse,
    summary="Get content recommendations for a student",
    description=(
        "Returns ranked content recommendations based on student weaknesses. "
        "Optionally filter by subject and limit results. Uses ML model with "
        "knowledge-graph fallback."
    ),
)
async def get_recommendations(
    student_id: str,
    subject: str | None = Query(None, description="Filter recommendations by subject"),
    limit: int = Query(5, ge=1, le=20, description="Maximum number of recommendations"),
    service=Depends(get_recommendation_service),
) -> RecommendationResponse:
    """Get ranked content recommendations for a student."""
    return service.predict(student_id=student_id, subject=subject, limit=limit)