app/api/v2/mastery.py

"""Mastery prediction API router.

Exposes POST /ai/v2/predict-mastery for per-student per-LO mastery inference.
"""

from fastapi import APIRouter, Depends

from app.api.v2.dependencies import get_mastery_service
from app.schemas.mastery import MasteryRequest, MasteryResponse

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


@router.post(
    "/predict-mastery",
    response_model=MasteryResponse,
    summary="Predict student mastery for a learning outcome",
    description=(
        "Returns mastery score, label, confidence, reasons, and recommended action "
        "for a given student and learning outcome. Uses ML model with rule-based fallback."
    ),
)
async def predict_mastery(
    request: MasteryRequest,
    service=Depends(get_mastery_service),
) -> MasteryResponse:
    """Predict mastery score and label for a student-LO pair."""
    return service.predict(student_id=request.student_id, lo_id=request.lo_id)