Deploy AI service with FastAPI

.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.env
+.env.local
+*.log
+.pytest_cache/
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store

Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+WORKDIR /app
+RUN apt-get update && apt-get install -y gcc g++ curl && rm -rf /var/lib/apt/lists/*
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY app/ ./app/
+COPY training/ ./training/
+RUN mkdir -p /data/artifacts/{models,feedback,reports,metrics}
+ENV MODEL_ARTIFACT_DIR=/data/artifacts/models
+ENV DATASET_DIR=/data/learning_outcome_os_dataset_v2
+ENV LOG_LEVEL=INFO
+EXPOSE 7860
+CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:7860", "--timeout", "120", "app.main:app"]

app/__init__.py

@@ -0,0 +1 @@
+# AI_Services_V2 app package

app/api/__init__.py

@@ -0,0 +1 @@
+# API package

app/api/v2/__init__.py

@@ -0,0 +1 @@
+# API v2 package

app/api/v2/answer_evaluation.py

@@ -0,0 +1,36 @@
+"""Answer evaluation router.
+
+POST /ai/v2/evaluate-answer — scores a subjective answer and flags for teacher review.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_answer_evaluation_service
+from app.schemas.answer_evaluation import AnswerEvaluationRequest, AnswerEvaluationResponse
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.post(
+    "/evaluate-answer",
+    response_model=AnswerEvaluationResponse,
+    summary="Evaluate Answer",
+    description="Score a subjective answer and flag for teacher review.",
+)
+async def evaluate_answer(
+    request: AnswerEvaluationRequest,
+    service=Depends(get_answer_evaluation_service),
+) -> AnswerEvaluationResponse:
+    """Score a student's subjective answer against a rubric."""
+    return service.predict(
+        question_id=request.question_id,
+        question_text=request.question_text,
+        student_answer=request.student_answer,
+        model_answer=request.model_answer,
+        rubric=request.rubric,
+        max_marks=request.max_marks,
+        grade=request.grade,
+        subject=request.subject,
+        lo_id=request.lo_id,
+        bloom_level=request.bloom_level,
+    )

app/api/v2/bloom.py

@@ -0,0 +1,35 @@
+"""Bloom classification API router.
+
+POST /ai/v2/classify-bloom — classifies a question's cognitive level
+according to Bloom's taxonomy.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_bloom_service
+from app.schemas.bloom import BloomRequest, BloomResponse
+from app.services.bloom_service import BloomService
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.post(
+    "/classify-bloom",
+    response_model=BloomResponse,
+    summary="Classify Bloom Level",
+    description=(
+        "Classify a question's cognitive level according to Bloom's taxonomy. "
+        "Returns the predicted Bloom level with confidence and an explanation."
+    ),
+)
+async def classify_bloom(
+    request: BloomRequest,
+    service: BloomService = Depends(get_bloom_service),
+) -> BloomResponse:
+    """Classify a question's Bloom taxonomy level."""
+    return service.predict(
+        question_text=request.question_text,
+        grade=request.grade,
+        subject=request.subject,
+        question_type=request.question_type,
+    )

app/api/v2/class_insights.py

@@ -0,0 +1,27 @@
+"""Class insights router.
+
+GET /ai/v2/class-insights/{class_id} — returns class-level weak LOs,
+at-risk counts, and recommended interventions.
+"""
+
+from fastapi import APIRouter, Depends, Query
+
+from app.api.v2.dependencies import get_class_insights_service
+from app.schemas.class_insights import ClassInsightsResponse
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.get(
+    "/class-insights/{class_id}",
+    response_model=ClassInsightsResponse,
+    summary="Get Class Insights",
+    description="Return class-level insights including weakest LOs, at-risk students, and interventions.",
+)
+async def get_class_insights(
+    class_id: str,
+    subject: str | None = Query(None, description="Optional subject filter"),
+    service=Depends(get_class_insights_service),
+) -> ClassInsightsResponse:
+    """Retrieve class-level insights for a teacher."""
+    return service.get_insights(class_id=class_id, subject=subject)

app/api/v2/dependencies.py

@@ -0,0 +1,98 @@
+"""FastAPI dependency providers for service instances.
+
+Each provider retrieves the service from request.app.state.services (the
+ServiceContainer attached during application lifespan startup).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import Request
+
+from app.data.loader import DatasetLoader
+from app.models.registry import ModelRegistry
+from app.monitoring.prediction_logger import PredictionLogger
+from app.services.explanation_service import ExplanationService
+
+
+@dataclass
+class ServiceContainer:
+    """Holds all service instances initialized at startup.
+
+    Services that have not yet been implemented are typed as Any and
+    set to None until their implementation tasks are completed.
+    """
+
+    registry: ModelRegistry
+    loader: DatasetLoader
+    explainer: ExplanationService
+    pred_logger: PredictionLogger
+
+    # Inference services — set to None until implemented (tasks 4.x, 5.x, 6.x)
+    lo_tagging: Any = None
+    bloom: Any = None
+    mastery: Any = None
+    risk: Any = None
+    recommendation: Any = None
+    answer_evaluation: Any = None
+    student_profile: Any = None
+    class_insights: Any = None
+    teacher_feedback: Any = None
+    monitoring: Any = None
+
+
+def get_service_container(request: Request) -> ServiceContainer:
+    """Retrieve the full ServiceContainer from app state."""
+    return request.app.state.services
+
+
+def get_lo_tagging_service(request: Request) -> Any:
+    """Provide the LO tagging service instance."""
+    return request.app.state.services.lo_tagging
+
+
+def get_bloom_service(request: Request) -> Any:
+    """Provide the Bloom classification service instance."""
+    return request.app.state.services.bloom
+
+
+def get_mastery_service(request: Request) -> Any:
+    """Provide the mastery prediction service instance."""
+    return request.app.state.services.mastery
+
+
+def get_risk_service(request: Request) -> Any:
+    """Provide the risk prediction service instance."""
+    return request.app.state.services.risk
+
+
+def get_recommendation_service(request: Request) -> Any:
+    """Provide the recommendation service instance."""
+    return request.app.state.services.recommendation
+
+
+def get_answer_evaluation_service(request: Request) -> Any:
+    """Provide the answer evaluation service instance."""
+    return request.app.state.services.answer_evaluation
+
+
+def get_student_profile_service(request: Request) -> Any:
+    """Provide the student profile service instance."""
+    return request.app.state.services.student_profile
+
+
+def get_class_insights_service(request: Request) -> Any:
+    """Provide the class insights service instance."""
+    return request.app.state.services.class_insights
+
+
+def get_teacher_feedback_service(request: Request) -> Any:
+    """Provide the teacher feedback service instance."""
+    return request.app.state.services.teacher_feedback
+
+
+def get_monitoring_service(request: Request) -> Any:
+    """Provide the monitoring service instance."""
+    return request.app.state.services.monitoring

app/api/v2/health.py

@@ -0,0 +1,55 @@
+"""Health and data summary API endpoints.
+
+Provides service health status and cached dataset summary information.
+These endpoints are lightweight and respond quickly regardless of model state.
+"""
+
+import logging
+
+from fastapi import APIRouter, Request
+
+from app.core.config import settings
+from app.schemas.health import DataSummaryResponse, HealthResponse
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/ai/v2", tags=["health"])
+
+
+@router.get(
+    "/health",
+    response_model=HealthResponse,
+    summary="Service health check",
+    description="Returns service status, version, and model loading state. Responds within 200ms.",
+)
+async def health_check() -> HealthResponse:
+    """Service health status. Must respond < 200ms."""
+    return HealthResponse(
+        status="ok",
+        service=settings.ai_service_name,
+        version=settings.ai_service_version,
+        models_loaded=False,
+    )
+
+
+@router.get(
+    "/data/summary",
+    response_model=DataSummaryResponse,
+    summary="Dataset summary",
+    description="Returns cached dataset metadata including table counts and validation status.",
+)
+async def data_summary(request: Request) -> DataSummaryResponse:
+    """Dataset status and table counts (cached at startup)."""
+    cached_metadata: dict = getattr(request.app.state, "dataset_metadata", None) or {
+        "version": "unknown",
+        "table_counts": {},
+        "validation_status": "not_run",
+        "total_issues": 0,
+    }
+
+    return DataSummaryResponse(
+        dataset_version=cached_metadata.get("version", "unknown"),
+        table_counts=cached_metadata.get("table_counts", {}),
+        validation_status=cached_metadata.get("validation_status", "not_run"),
+        total_issues=cached_metadata.get("total_issues", 0),
+    )

app/api/v2/lo_tagging.py

@@ -0,0 +1,36 @@
+"""LO tagging API router.
+
+POST /ai/v2/tag-learning-outcome — predicts the most relevant learning outcome
+for a given question with confidence and explanation.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_lo_tagging_service
+from app.schemas.lo_tagging import LOTaggingRequest, LOTaggingResponse
+from app.services.lo_tagging_service import LOTaggingService
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.post(
+    "/tag-learning-outcome",
+    response_model=LOTaggingResponse,
+    summary="Tag Learning Outcome",
+    description=(
+        "Predict the most relevant learning outcome for a given question. "
+        "Returns top-k predictions with confidence scores and an explanation."
+    ),
+)
+async def tag_learning_outcome(
+    request: LOTaggingRequest,
+    service: LOTaggingService = Depends(get_lo_tagging_service),
+) -> LOTaggingResponse:
+    """Predict the most relevant learning outcome for a question."""
+    return service.predict(
+        question_text=request.question_text,
+        grade=request.grade,
+        subject=request.subject,
+        chapter=request.chapter,
+        top_k=request.top_k,
+    )

app/api/v2/mastery.py

@@ -0,0 +1,28 @@
+"""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)

app/api/v2/monitoring.py

@@ -0,0 +1,30 @@
+"""Monitoring API router.
+
+GET /ai/v2/monitoring/model-health — returns status of all loaded models
+with metrics and prediction stats.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_monitoring_service
+from app.schemas.monitoring import MonitoringResponse
+from app.services.monitoring_service import MonitoringService
+
+router = APIRouter(prefix="/ai/v2", tags=["monitoring"])
+
+
+@router.get(
+    "/monitoring/model-health",
+    response_model=MonitoringResponse,
+    summary="Model Health",
+    description=(
+        "Return status of all loaded models with metrics and prediction stats. "
+        "Reports model version, last trained date, key metrics, "
+        "and prediction counts for the last 24 hours."
+    ),
+)
+async def get_model_health(
+    service: MonitoringService = Depends(get_monitoring_service),
+) -> MonitoringResponse:
+    """Return health status of all registered models."""
+    return service.get_model_health()

app/api/v2/recommendations.py

@@ -0,0 +1,31 @@
+"""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)

app/api/v2/risk.py

@@ -0,0 +1,28 @@
+"""Risk prediction API router.
+
+Exposes GET /ai/v2/risk/{student_id} for student risk inference.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_risk_service
+from app.schemas.risk import RiskResponse
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.get(
+    "/risk/{student_id}",
+    response_model=RiskResponse,
+    summary="Predict student risk level",
+    description=(
+        "Returns risk score, 4-class label, reasons, and recommended intervention "
+        "for a given student. Uses ML model with rule-based fallback."
+    ),
+)
+async def predict_risk(
+    student_id: str,
+    service=Depends(get_risk_service),
+) -> RiskResponse:
+    """Predict risk score and label for a student."""
+    return service.predict(student_id=student_id)

app/api/v2/student_profile.py

@@ -0,0 +1,25 @@
+"""Student profile router.
+
+GET /ai/v2/student-profile/{student_id} — returns a digital twin aggregation.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_student_profile_service
+from app.schemas.student_profile import StudentProfileResponse
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.get(
+    "/student-profile/{student_id}",
+    response_model=StudentProfileResponse,
+    summary="Get Student Profile",
+    description="Return a digital twin aggregation for a student.",
+)
+async def get_student_profile(
+    student_id: str,
+    service=Depends(get_student_profile_service),
+) -> StudentProfileResponse:
+    """Retrieve the aggregated student profile (digital twin)."""
+    return service.get_profile(student_id=student_id)

app/api/v2/teacher_feedback.py

@@ -0,0 +1,38 @@
+"""Teacher feedback API router.
+
+POST /ai/v2/teacher-feedback — stores teacher feedback on a prediction
+for future retraining.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_teacher_feedback_service
+from app.schemas.teacher_feedback import TeacherFeedbackRequest, TeacherFeedbackResponse
+from app.services.teacher_feedback_service import TeacherFeedbackService
+
+router = APIRouter(prefix="/ai/v2", tags=["feedback"])
+
+
+@router.post(
+    "/teacher-feedback",
+    response_model=TeacherFeedbackResponse,
+    summary="Submit Teacher Feedback",
+    description=(
+        "Store teacher feedback on a prediction for future retraining. "
+        "Feedback types: accept, edit, reject. "
+        "If feedback_type is 'edit', corrected_label is required."
+    ),
+)
+async def submit_teacher_feedback(
+    request: TeacherFeedbackRequest,
+    service: TeacherFeedbackService = Depends(get_teacher_feedback_service),
+) -> TeacherFeedbackResponse:
+    """Store teacher feedback referencing a prediction."""
+    return service.store_feedback(
+        teacher_id=request.teacher_id,
+        prediction_id=request.prediction_id,
+        feedback_type=request.feedback_type,
+        corrected_label=request.corrected_label,
+        rating=request.rating,
+        comment=request.comment,
+    )

app/app/__init__.py

@@ -0,0 +1 @@
+# AI_Services_V2 app package

app/app/api/__init__.py

@@ -0,0 +1 @@
+# API package

app/app/api/v2/__init__.py

@@ -0,0 +1 @@
+# API v2 package

app/app/api/v2/answer_evaluation.py

@@ -0,0 +1,36 @@
+"""Answer evaluation router.
+
+POST /ai/v2/evaluate-answer — scores a subjective answer and flags for teacher review.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_answer_evaluation_service
+from app.schemas.answer_evaluation import AnswerEvaluationRequest, AnswerEvaluationResponse
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.post(
+    "/evaluate-answer",
+    response_model=AnswerEvaluationResponse,
+    summary="Evaluate Answer",
+    description="Score a subjective answer and flag for teacher review.",
+)
+async def evaluate_answer(
+    request: AnswerEvaluationRequest,
+    service=Depends(get_answer_evaluation_service),
+) -> AnswerEvaluationResponse:
+    """Score a student's subjective answer against a rubric."""
+    return service.predict(
+        question_id=request.question_id,
+        question_text=request.question_text,
+        student_answer=request.student_answer,
+        model_answer=request.model_answer,
+        rubric=request.rubric,
+        max_marks=request.max_marks,
+        grade=request.grade,
+        subject=request.subject,
+        lo_id=request.lo_id,
+        bloom_level=request.bloom_level,
+    )

app/app/api/v2/bloom.py

@@ -0,0 +1,35 @@
+"""Bloom classification API router.
+
+POST /ai/v2/classify-bloom — classifies a question's cognitive level
+according to Bloom's taxonomy.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_bloom_service
+from app.schemas.bloom import BloomRequest, BloomResponse
+from app.services.bloom_service import BloomService
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.post(
+    "/classify-bloom",
+    response_model=BloomResponse,
+    summary="Classify Bloom Level",
+    description=(
+        "Classify a question's cognitive level according to Bloom's taxonomy. "
+        "Returns the predicted Bloom level with confidence and an explanation."
+    ),
+)
+async def classify_bloom(
+    request: BloomRequest,
+    service: BloomService = Depends(get_bloom_service),
+) -> BloomResponse:
+    """Classify a question's Bloom taxonomy level."""
+    return service.predict(
+        question_text=request.question_text,
+        grade=request.grade,
+        subject=request.subject,
+        question_type=request.question_type,
+    )

app/app/api/v2/class_insights.py

@@ -0,0 +1,27 @@
+"""Class insights router.
+
+GET /ai/v2/class-insights/{class_id} — returns class-level weak LOs,
+at-risk counts, and recommended interventions.
+"""
+
+from fastapi import APIRouter, Depends, Query
+
+from app.api.v2.dependencies import get_class_insights_service
+from app.schemas.class_insights import ClassInsightsResponse
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.get(
+    "/class-insights/{class_id}",
+    response_model=ClassInsightsResponse,
+    summary="Get Class Insights",
+    description="Return class-level insights including weakest LOs, at-risk students, and interventions.",
+)
+async def get_class_insights(
+    class_id: str,
+    subject: str | None = Query(None, description="Optional subject filter"),
+    service=Depends(get_class_insights_service),
+) -> ClassInsightsResponse:
+    """Retrieve class-level insights for a teacher."""
+    return service.get_insights(class_id=class_id, subject=subject)

app/app/api/v2/dependencies.py

@@ -0,0 +1,98 @@
+"""FastAPI dependency providers for service instances.
+
+Each provider retrieves the service from request.app.state.services (the
+ServiceContainer attached during application lifespan startup).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import Request
+
+from app.data.loader import DatasetLoader
+from app.models.registry import ModelRegistry
+from app.monitoring.prediction_logger import PredictionLogger
+from app.services.explanation_service import ExplanationService
+
+
+@dataclass
+class ServiceContainer:
+    """Holds all service instances initialized at startup.
+
+    Services that have not yet been implemented are typed as Any and
+    set to None until their implementation tasks are completed.
+    """
+
+    registry: ModelRegistry
+    loader: DatasetLoader
+    explainer: ExplanationService
+    pred_logger: PredictionLogger
+
+    # Inference services — set to None until implemented (tasks 4.x, 5.x, 6.x)
+    lo_tagging: Any = None
+    bloom: Any = None
+    mastery: Any = None
+    risk: Any = None
+    recommendation: Any = None
+    answer_evaluation: Any = None
+    student_profile: Any = None
+    class_insights: Any = None
+    teacher_feedback: Any = None
+    monitoring: Any = None
+
+
+def get_service_container(request: Request) -> ServiceContainer:
+    """Retrieve the full ServiceContainer from app state."""
+    return request.app.state.services
+
+
+def get_lo_tagging_service(request: Request) -> Any:
+    """Provide the LO tagging service instance."""
+    return request.app.state.services.lo_tagging
+
+
+def get_bloom_service(request: Request) -> Any:
+    """Provide the Bloom classification service instance."""
+    return request.app.state.services.bloom
+
+
+def get_mastery_service(request: Request) -> Any:
+    """Provide the mastery prediction service instance."""
+    return request.app.state.services.mastery
+
+
+def get_risk_service(request: Request) -> Any:
+    """Provide the risk prediction service instance."""
+    return request.app.state.services.risk
+
+
+def get_recommendation_service(request: Request) -> Any:
+    """Provide the recommendation service instance."""
+    return request.app.state.services.recommendation
+
+
+def get_answer_evaluation_service(request: Request) -> Any:
+    """Provide the answer evaluation service instance."""
+    return request.app.state.services.answer_evaluation
+
+
+def get_student_profile_service(request: Request) -> Any:
+    """Provide the student profile service instance."""
+    return request.app.state.services.student_profile
+
+
+def get_class_insights_service(request: Request) -> Any:
+    """Provide the class insights service instance."""
+    return request.app.state.services.class_insights
+
+
+def get_teacher_feedback_service(request: Request) -> Any:
+    """Provide the teacher feedback service instance."""
+    return request.app.state.services.teacher_feedback
+
+
+def get_monitoring_service(request: Request) -> Any:
+    """Provide the monitoring service instance."""
+    return request.app.state.services.monitoring

app/app/api/v2/health.py

@@ -0,0 +1,55 @@
+"""Health and data summary API endpoints.
+
+Provides service health status and cached dataset summary information.
+These endpoints are lightweight and respond quickly regardless of model state.
+"""
+
+import logging
+
+from fastapi import APIRouter, Request
+
+from app.core.config import settings
+from app.schemas.health import DataSummaryResponse, HealthResponse
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/ai/v2", tags=["health"])
+
+
+@router.get(
+    "/health",
+    response_model=HealthResponse,
+    summary="Service health check",
+    description="Returns service status, version, and model loading state. Responds within 200ms.",
+)
+async def health_check() -> HealthResponse:
+    """Service health status. Must respond < 200ms."""
+    return HealthResponse(
+        status="ok",
+        service=settings.ai_service_name,
+        version=settings.ai_service_version,
+        models_loaded=False,
+    )
+
+
+@router.get(
+    "/data/summary",
+    response_model=DataSummaryResponse,
+    summary="Dataset summary",
+    description="Returns cached dataset metadata including table counts and validation status.",
+)
+async def data_summary(request: Request) -> DataSummaryResponse:
+    """Dataset status and table counts (cached at startup)."""
+    cached_metadata: dict = getattr(request.app.state, "dataset_metadata", None) or {
+        "version": "unknown",
+        "table_counts": {},
+        "validation_status": "not_run",
+        "total_issues": 0,
+    }
+
+    return DataSummaryResponse(
+        dataset_version=cached_metadata.get("version", "unknown"),
+        table_counts=cached_metadata.get("table_counts", {}),
+        validation_status=cached_metadata.get("validation_status", "not_run"),
+        total_issues=cached_metadata.get("total_issues", 0),
+    )

app/app/api/v2/lo_tagging.py

@@ -0,0 +1,36 @@
+"""LO tagging API router.
+
+POST /ai/v2/tag-learning-outcome — predicts the most relevant learning outcome
+for a given question with confidence and explanation.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_lo_tagging_service
+from app.schemas.lo_tagging import LOTaggingRequest, LOTaggingResponse
+from app.services.lo_tagging_service import LOTaggingService
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.post(
+    "/tag-learning-outcome",
+    response_model=LOTaggingResponse,
+    summary="Tag Learning Outcome",
+    description=(
+        "Predict the most relevant learning outcome for a given question. "
+        "Returns top-k predictions with confidence scores and an explanation."
+    ),
+)
+async def tag_learning_outcome(
+    request: LOTaggingRequest,
+    service: LOTaggingService = Depends(get_lo_tagging_service),
+) -> LOTaggingResponse:
+    """Predict the most relevant learning outcome for a question."""
+    return service.predict(
+        question_text=request.question_text,
+        grade=request.grade,
+        subject=request.subject,
+        chapter=request.chapter,
+        top_k=request.top_k,
+    )

app/app/api/v2/mastery.py

@@ -0,0 +1,28 @@
+"""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)

app/app/api/v2/monitoring.py

@@ -0,0 +1,30 @@
+"""Monitoring API router.
+
+GET /ai/v2/monitoring/model-health — returns status of all loaded models
+with metrics and prediction stats.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_monitoring_service
+from app.schemas.monitoring import MonitoringResponse
+from app.services.monitoring_service import MonitoringService
+
+router = APIRouter(prefix="/ai/v2", tags=["monitoring"])
+
+
+@router.get(
+    "/monitoring/model-health",
+    response_model=MonitoringResponse,
+    summary="Model Health",
+    description=(
+        "Return status of all loaded models with metrics and prediction stats. "
+        "Reports model version, last trained date, key metrics, "
+        "and prediction counts for the last 24 hours."
+    ),
+)
+async def get_model_health(
+    service: MonitoringService = Depends(get_monitoring_service),
+) -> MonitoringResponse:
+    """Return health status of all registered models."""
+    return service.get_model_health()

app/app/api/v2/recommendations.py

@@ -0,0 +1,31 @@
+"""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)

app/app/api/v2/risk.py

@@ -0,0 +1,28 @@
+"""Risk prediction API router.
+
+Exposes GET /ai/v2/risk/{student_id} for student risk inference.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_risk_service
+from app.schemas.risk import RiskResponse
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.get(
+    "/risk/{student_id}",
+    response_model=RiskResponse,
+    summary="Predict student risk level",
+    description=(
+        "Returns risk score, 4-class label, reasons, and recommended intervention "
+        "for a given student. Uses ML model with rule-based fallback."
+    ),
+)
+async def predict_risk(
+    student_id: str,
+    service=Depends(get_risk_service),
+) -> RiskResponse:
+    """Predict risk score and label for a student."""
+    return service.predict(student_id=student_id)

app/app/api/v2/student_profile.py

@@ -0,0 +1,25 @@
+"""Student profile router.
+
+GET /ai/v2/student-profile/{student_id} — returns a digital twin aggregation.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_student_profile_service
+from app.schemas.student_profile import StudentProfileResponse
+
+router = APIRouter(prefix="/ai/v2", tags=["inference"])
+
+
+@router.get(
+    "/student-profile/{student_id}",
+    response_model=StudentProfileResponse,
+    summary="Get Student Profile",
+    description="Return a digital twin aggregation for a student.",
+)
+async def get_student_profile(
+    student_id: str,
+    service=Depends(get_student_profile_service),
+) -> StudentProfileResponse:
+    """Retrieve the aggregated student profile (digital twin)."""
+    return service.get_profile(student_id=student_id)

app/app/api/v2/teacher_feedback.py

@@ -0,0 +1,38 @@
+"""Teacher feedback API router.
+
+POST /ai/v2/teacher-feedback — stores teacher feedback on a prediction
+for future retraining.
+"""
+
+from fastapi import APIRouter, Depends
+
+from app.api.v2.dependencies import get_teacher_feedback_service
+from app.schemas.teacher_feedback import TeacherFeedbackRequest, TeacherFeedbackResponse
+from app.services.teacher_feedback_service import TeacherFeedbackService
+
+router = APIRouter(prefix="/ai/v2", tags=["feedback"])
+
+
+@router.post(
+    "/teacher-feedback",
+    response_model=TeacherFeedbackResponse,
+    summary="Submit Teacher Feedback",
+    description=(
+        "Store teacher feedback on a prediction for future retraining. "
+        "Feedback types: accept, edit, reject. "
+        "If feedback_type is 'edit', corrected_label is required."
+    ),
+)
+async def submit_teacher_feedback(
+    request: TeacherFeedbackRequest,
+    service: TeacherFeedbackService = Depends(get_teacher_feedback_service),
+) -> TeacherFeedbackResponse:
+    """Store teacher feedback referencing a prediction."""
+    return service.store_feedback(
+        teacher_id=request.teacher_id,
+        prediction_id=request.prediction_id,
+        feedback_type=request.feedback_type,
+        corrected_label=request.corrected_label,
+        rating=request.rating,
+        comment=request.comment,
+    )

app/app/core/__init__.py

@@ -0,0 +1 @@
+# Core package

app/app/core/config.py

@@ -0,0 +1,29 @@
+"""Centralized configuration system using pydantic-settings.
+
+All environment-driven settings are defined here. No module outside this file
+should read os.environ directly.
+"""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables and .env file."""
+
+    ai_service_name: str = "LearningOutcomeOS-AI-V2"
+    ai_service_version: str = "2.0.0"
+    dataset_dir: str = "../learning_outcome_os_dataset_v2"
+    model_artifact_dir: str = "../artifacts/models"
+    metrics_dir: str = "../artifacts/metrics"
+    reports_dir: str = "../artifacts/reports"
+    log_level: str = "INFO"
+    seed: int = 20260520
+    low_confidence_threshold: float = 0.55
+    enable_explainability: bool = True
+    log_salt: str = "change-me-in-prod"
+    feedback_dir: str = "./artifacts/feedback"
+
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+
+settings = Settings()

app/app/core/constants.py

@@ -0,0 +1,30 @@
+"""Application-wide constants.
+
+These values define the authoritative label sets and mappings used across
+inference services, schemas, and validation. They must match the data contract
+exactly and should never be redefined elsewhere in the codebase.
+"""
+
+MASTERY_LABEL_MAP: dict[int, str] = {
+    0: "weak",
+    1: "developing",
+    2: "proficient",
+    3: "mastered",
+}
+
+BLOOM_LEVELS: list[str] = [
+    "Remember",
+    "Understand",
+    "Apply",
+    "Analyze",
+    "Evaluate",
+    "Create",
+]
+
+RISK_LABELS: list[str] = ["low", "medium", "high", "critical"]
+
+FEEDBACK_TYPES: list[str] = ["accept", "edit", "reject"]
+
+VALID_SUBJECTS: list[str] = ["Mathematics", "Science", "Social Science"]
+
+VALID_GRADES: list[int] = [6, 7, 8]

app/app/core/exceptions.py

@@ -0,0 +1,26 @@
+"""Custom exception classes for the AI Services V2 layer."""
+
+
+class DatasetError(Exception):
+    """Raised when dataset operations fail (missing file, schema mismatch)."""
+
+
+class TrainingError(Exception):
+    """Raised when a model training pipeline fails.
+
+    Attributes:
+        model_name: The name of the model whose training failed.
+        message: Human-readable description of the failure.
+    """
+
+    def __init__(self, message: str, model_name: str) -> None:
+        self.model_name = model_name
+        super().__init__(f"[{model_name}] {message}")
+
+
+class ModelNotLoadedError(Exception):
+    """Raised when inference is attempted on an unloaded model."""
+
+
+class EntityNotFoundError(Exception):
+    """Raised when a referenced entity (student, LO, class) doesn't exist."""

app/app/data/__init__.py

@@ -0,0 +1 @@
+# Data package

app/app/data/loader.py

@@ -0,0 +1,124 @@
+"""Dataset loader for CSV tables and metadata.
+
+Provides a single abstraction for loading any CSV table or the dataset
+metadata JSON from the configured dataset directory. All path resolution
+is relative to the dataset_dir parameter — no hardcoded paths.
+"""
+
+import json
+import logging
+from pathlib import Path
+
+import pandas as pd
+
+from app.core.exceptions import DatasetError
+
+logger = logging.getLogger(__name__)
+
+
+class DatasetLoader:
+    """Loads CSV tables and metadata from the dataset directory.
+
+    All file paths are resolved relative to the dataset_dir provided at
+    construction time. Table names are accepted with or without the .csv
+    extension. No columns are renamed, dropped, or aliased during loading.
+    """
+
+    def __init__(self, dataset_dir: str | Path) -> None:
+        self._dataset_dir = Path(dataset_dir).resolve()
+
+    @property
+    def dataset_dir(self) -> Path:
+        """The resolved dataset directory path."""
+        return self._dataset_dir
+
+    def load_table(self, table_name: str) -> pd.DataFrame:
+        """Load a CSV table by name and return it as a DataFrame.
+
+        Accepts table names with or without the .csv extension
+        (e.g., "learning_outcomes" or "learning_outcomes.csv").
+
+        Args:
+            table_name: Name of the CSV table to load.
+
+        Returns:
+            A pandas DataFrame with the table contents.
+
+        Raises:
+            DatasetError: If the CSV file does not exist at the resolved path.
+        """
+        path = self.get_table_path(table_name)
+
+        if not path.exists():
+            raise DatasetError(
+                f"Table file not found: {path}"
+            )
+
+        try:
+            df = pd.read_csv(path)
+        except Exception as exc:
+            raise DatasetError(
+                f"Failed to read table '{table_name}' at {path}: {exc}"
+            ) from exc
+
+        logger.info("Loaded table '%s' — %d rows, %d columns", table_name, len(df), len(df.columns))
+        return df
+
+    def load_metadata(self) -> dict:
+        """Load and parse dataset_metadata.json from the dataset directory.
+
+        Returns:
+            A dictionary with the parsed JSON content.
+
+        Raises:
+            DatasetError: If the metadata file does not exist or cannot be parsed.
+        """
+        path = self._dataset_dir / "dataset_metadata.json"
+
+        if not path.exists():
+            raise DatasetError(
+                f"Metadata file not found: {path}"
+            )
+
+        try:
+            with open(path, encoding="utf-8") as f:
+                metadata = json.load(f)
+        except json.JSONDecodeError as exc:
+            raise DatasetError(
+                f"Failed to parse metadata JSON at {path}: {exc}"
+            ) from exc
+        except Exception as exc:
+            raise DatasetError(
+                f"Failed to read metadata file at {path}: {exc}"
+            ) from exc
+
+        logger.info("Loaded dataset metadata from %s", path)
+        return metadata
+
+    def list_tables(self) -> list[str]:
+        """Return a list of available CSV table names without extension.
+
+        Scans the dataset directory for .csv files and returns their
+        stem names (e.g., "learning_outcomes", "student_profiles").
+
+        Returns:
+            A sorted list of table name strings without the .csv extension.
+        """
+        csv_files = sorted(self._dataset_dir.glob("*.csv"))
+        return [f.stem for f in csv_files]
+
+    def get_table_path(self, table_name: str) -> Path:
+        """Resolve the full path for a table name.
+
+        Handles table names with or without the .csv extension.
+        Does NOT verify that the file exists.
+
+        Args:
+            table_name: Name of the table (with or without .csv extension).
+
+        Returns:
+            The resolved Path to the CSV file.
+        """
+        if not table_name.endswith(".csv"):
+            table_name = f"{table_name}.csv"
+        return self._dataset_dir / table_name

app/app/data/split_manager.py

@@ -0,0 +1,67 @@
+"""Split manager for separating DataFrames by train_split column."""
+
+from typing import ClassVar
+
+import pandas as pd
+
+from app.core.exceptions import DatasetError
+
+
+class SplitManager:
+    """Separates DataFrames by train_split column into train/validation/test."""
+
+    VALID_SPLITS: ClassVar[set[str]] = {"train", "validation", "test"}
+
+    def get_splits(
+        self, df: pd.DataFrame, split_col: str = "train_split"
+    ) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+        """Return (train_df, val_df, test_df) as new DataFrame copies.
+
+        Raises DatasetError if split_col missing or contains invalid values.
+        """
+        if split_col not in df.columns:
+            raise DatasetError(
+                f"Column '{split_col}' not found in DataFrame. "
+                f"Available columns: {list(df.columns)}. "
+                f"This table may not be a training table."
+            )
+
+        unique_values = set(df[split_col].dropna().unique())
+        invalid_values = unique_values - self.VALID_SPLITS
+
+        if invalid_values:
+            raise DatasetError(
+                f"Column '{split_col}' contains invalid values: {sorted(invalid_values)}. "
+                f"Only {sorted(self.VALID_SPLITS)} are allowed."
+            )
+
+        # Check for null/empty values in the split column
+        null_count = df[split_col].isna().sum()
+        if null_count > 0:
+            raise DatasetError(
+                f"Column '{split_col}' contains {null_count} null value(s). "
+                f"All rows must have a valid split assignment."
+            )
+
+        empty_count = (df[split_col] == "").sum()
+        if empty_count > 0:
+            raise DatasetError(
+                f"Column '{split_col}' contains {empty_count} empty string value(s). "
+                f"All rows must have a valid split assignment from {sorted(self.VALID_SPLITS)}."
+            )
+
+        # Filter by column value only — no random sampling, shuffling, or sklearn splitters
+        train_df = df[df[split_col] == "train"].copy()
+        val_df = df[df[split_col] == "validation"].copy()
+        test_df = df[df[split_col] == "test"].copy()
+
+        # Verify row conservation
+        total_split_rows = len(train_df) + len(val_df) + len(test_df)
+        if total_split_rows != len(df):
+            raise DatasetError(
+                f"Row conservation violated: split rows ({total_split_rows}) "
+                f"!= original rows ({len(df)}). "
+                f"This indicates data corruption or unexpected split values."
+            )
+
+        return train_df, val_df, test_df

app/app/data/validator.py

@@ -0,0 +1,481 @@
+"""Dataset validator for integrity checks.
+
+Validates dataset integrity against metadata expectations: table presence,
+row counts, null values, foreign key relationships, split columns, and
+target label columns. Uses the collect-all-errors pattern — reports every
+issue in one pass rather than failing fast.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+import pandas as pd
+
+from app.core.exceptions import DatasetError
+from app.data.loader import DatasetLoader
+
+logger = logging.getLogger(__name__)
+
+
+# Tables that must contain a train_split column with exactly {train, validation, test}
+TRAINING_TABLES: list[str] = [
+    "training_lo_tagging",
+    "training_bloom_classification",
+    "training_risk_prediction",
+    "training_mastery_prediction",
+    "training_answer_scoring",
+    "training_recommendation_outcomes",
+    "learning_outcomes",
+    "questions",
+    "student_profiles",
+    "student_attempts",
+    "mastery_profiles",
+    "engagement_logs",
+    "risk_profiles",
+    "recommendations",
+    "content_catalog",
+]
+
+# Foreign key relationships: (child_table, child_column, parent_table, parent_column)
+FOREIGN_KEY_RELATIONSHIPS: list[tuple[str, str, str, str]] = [
+    ("student_attempts", "student_id", "student_profiles", "student_id"),
+    ("student_attempts", "question_id", "questions", "question_id"),
+    ("questions", "lo_id", "learning_outcomes", "lo_id"),
+    ("lo_dependencies", "lo_id", "learning_outcomes", "lo_id"),
+    ("lo_dependencies", "prerequisite_lo_id", "learning_outcomes", "lo_id"),
+]
+
+# Target columns that must exist in their respective tables
+TARGET_COLUMNS: list[tuple[str, str]] = [
+    ("training_lo_tagging", "lo_id"),
+    ("training_bloom_classification", "bloom_level"),
+    ("training_mastery_prediction", "mastery_label"),
+    ("training_risk_prediction", "risk_label"),
+    ("training_risk_prediction", "risk_level"),
+    ("training_answer_scoring", "teacher_marks"),
+    ("training_recommendation_outcomes", "clicked"),
+    ("training_recommendation_outcomes", "is_completed"),
+]
+
+VALID_SPLITS: set[str] = {"train", "validation", "test"}
+
+
+@dataclass
+class ValidationIssue:
+    """A single validation issue found during dataset checks."""
+
+    check: str
+    table: str
+    column: str | None
+    message: str
+    severity: str  # "error" | "warning"
+
+
+@dataclass
+class ValidationReport:
+    """Aggregated result of all validation checks."""
+
+    timestamp: datetime
+    passed: bool
+    issues: list[ValidationIssue] = field(default_factory=list)
+    checks_run: int = 0
+    checks_passed: int = 0
+
+
+class DatasetValidator:
+    """Validates dataset integrity against metadata expectations.
+
+    Uses the collect-all-errors pattern: every check runs to completion
+    and all issues are aggregated into a single report.
+    """
+
+    def __init__(self, loader: DatasetLoader, metadata: dict) -> None:
+        self._loader = loader
+        self._metadata = metadata
+
+    def check_table_presence(self) -> list[ValidationIssue]:
+        """Verify all expected CSV files from metadata are present.
+
+        Returns:
+            List of ValidationIssue for any missing tables.
+        """
+        issues: list[ValidationIssue] = []
+        table_counts = self._metadata.get("table_counts", {})
+
+        for table_file in table_counts:
+            table_name = table_file.replace(".csv", "")
+            path = self._loader.get_table_path(table_name)
+            if not path.exists():
+                issues.append(
+                    ValidationIssue(
+                        check="table_presence",
+                        table=table_name,
+                        column=None,
+                        message=f"Expected CSV file not found: {path}",
+                        severity="error",
+                    )
+                )
+
+        return issues
+
+    def check_row_counts(self) -> list[ValidationIssue]:
+        """Compare actual row counts against metadata expected counts.
+
+        Returns:
+            List of ValidationIssue for any row count mismatches.
+        """
+        issues: list[ValidationIssue] = []
+        table_counts = self._metadata.get("table_counts", {})
+
+        for table_file, expected_count in table_counts.items():
+            table_name = table_file.replace(".csv", "")
+            try:
+                df = self._loader.load_table(table_name)
+            except DatasetError:
+                # Table missing — already reported by check_table_presence
+                continue
+
+            actual_count = len(df)
+            if actual_count != expected_count:
+                issues.append(
+                    ValidationIssue(
+                        check="row_count",
+                        table=table_name,
+                        column=None,
+                        message=(
+                            f"Row count mismatch: expected {expected_count}, "
+                            f"got {actual_count}"
+                        ),
+                        severity="error",
+                    )
+                )
+
+        return issues
+
+    def check_null_values(self) -> list[ValidationIssue]:
+        """Confirm no CSV file contains any null values.
+
+        Returns:
+            List of ValidationIssue for any columns with null values.
+        """
+        issues: list[ValidationIssue] = []
+        table_counts = self._metadata.get("table_counts", {})
+
+        for table_file in table_counts:
+            table_name = table_file.replace(".csv", "")
+            try:
+                df = self._loader.load_table(table_name)
+            except DatasetError:
+                continue
+
+            null_counts = df.isnull().sum()
+            for col, count in null_counts.items():
+                if count > 0:
+                    issues.append(
+                        ValidationIssue(
+                            check="null_check",
+                            table=table_name,
+                            column=str(col),
+                            message=f"Column '{col}' has {count} null value(s)",
+                            severity="error",
+                        )
+                    )
+
+        return issues
+
+    def check_foreign_keys(self) -> list[ValidationIssue]:
+        """Validate all defined foreign key relationships.
+
+        Checks that all values in child columns are present in the
+        corresponding parent column.
+
+        Returns:
+            List of ValidationIssue for any FK violations.
+        """
+        issues: list[ValidationIssue] = []
+
+        for child_table, child_col, parent_table, parent_col in FOREIGN_KEY_RELATIONSHIPS:
+            try:
+                child_df = self._loader.load_table(child_table)
+                parent_df = self._loader.load_table(parent_table)
+            except DatasetError:
+                # Tables missing — already reported by check_table_presence
+                continue
+
+            if child_col not in child_df.columns:
+                issues.append(
+                    ValidationIssue(
+                        check="foreign_key",
+                        table=child_table,
+                        column=child_col,
+                        message=(
+                            f"FK column '{child_col}' not found in table '{child_table}'"
+                        ),
+                        severity="error",
+                    )
+                )
+                continue
+
+            if parent_col not in parent_df.columns:
+                issues.append(
+                    ValidationIssue(
+                        check="foreign_key",
+                        table=parent_table,
+                        column=parent_col,
+                        message=(
+                            f"Referenced column '{parent_col}' not found in "
+                            f"table '{parent_table}'"
+                        ),
+                        severity="error",
+                    )
+                )
+                continue
+
+            child_values = set(child_df[child_col].dropna().unique())
+            parent_values = set(parent_df[parent_col].dropna().unique())
+            orphans = child_values - parent_values
+
+            if orphans:
+                sample = sorted(str(v) for v in list(orphans)[:5])
+                issues.append(
+                    ValidationIssue(
+                        check="foreign_key",
+                        table=child_table,
+                        column=child_col,
+                        message=(
+                            f"FK violation: {len(orphans)} value(s) in "
+                            f"'{child_table}.{child_col}' not found in "
+                            f"'{parent_table}.{parent_col}'. "
+                            f"Sample: {sample}"
+                        ),
+                        severity="error",
+                    )
+                )
+
+        return issues
+
+    def check_split_presence(self) -> list[ValidationIssue]:
+        """Verify training tables have train_split column with exactly {train, validation, test}.
+
+        Returns:
+            List of ValidationIssue for any split column problems.
+        """
+        issues: list[ValidationIssue] = []
+
+        for table_name in TRAINING_TABLES:
+            try:
+                df = self._loader.load_table(table_name)
+            except DatasetError:
+                continue
+
+            if "train_split" not in df.columns:
+                issues.append(
+                    ValidationIssue(
+                        check="split_presence",
+                        table=table_name,
+                        column="train_split",
+                        message=(
+                            f"Training table '{table_name}' is missing "
+                            f"'train_split' column"
+                        ),
+                        severity="error",
+                    )
+                )
+                continue
+
+            actual_splits = set(df["train_split"].dropna().unique())
+
+            if actual_splits != VALID_SPLITS:
+                missing = VALID_SPLITS - actual_splits
+                extra = actual_splits - VALID_SPLITS
+                parts = []
+                if missing:
+                    parts.append(f"missing splits: {sorted(missing)}")
+                if extra:
+                    parts.append(f"unexpected splits: {sorted(extra)}")
+                issues.append(
+                    ValidationIssue(
+                        check="split_presence",
+                        table=table_name,
+                        column="train_split",
+                        message=(
+                            f"Split values mismatch in '{table_name}': "
+                            f"{'; '.join(parts)}. "
+                            f"Expected exactly {{train, validation, test}}, "
+                            f"got {sorted(actual_splits)}"
+                        ),
+                        severity="error",
+                    )
+                )
+
+        return issues
+
+    def check_target_labels(self) -> list[ValidationIssue]:
+        """Verify target columns exist in their respective training tables.
+
+        Returns:
+            List of ValidationIssue for any missing target columns.
+        """
+        issues: list[ValidationIssue] = []
+
+        for table_name, column_name in TARGET_COLUMNS:
+            try:
+                df = self._loader.load_table(table_name)
+            except DatasetError:
+                continue
+
+            if column_name not in df.columns:
+                issues.append(
+                    ValidationIssue(
+                        check="target_labels",
+                        table=table_name,
+                        column=column_name,
+                        message=(
+                            f"Target column '{column_name}' not found in "
+                            f"table '{table_name}'"
+                        ),
+                        severity="error",
+                    )
+                )
+
+        return issues
+
+    def run_all(self) -> ValidationReport:
+        """Execute all validation checks and aggregate results.
+
+        Uses the collect-all-errors pattern: every check runs regardless
+        of whether previous checks found issues.
+
+        Returns:
+            A ValidationReport with all issues and pass/fail status.
+        """
+        all_issues: list[ValidationIssue] = []
+        checks_run = 0
+        checks_passed = 0
+
+        checks = [
+            ("table_presence", self.check_table_presence),
+            ("row_counts", self.check_row_counts),
+            ("null_values", self.check_null_values),
+            ("foreign_keys", self.check_foreign_keys),
+            ("split_presence", self.check_split_presence),
+            ("target_labels", self.check_target_labels),
+        ]
+
+        for check_name, check_fn in checks:
+            checks_run += 1
+            try:
+                issues = check_fn()
+                all_issues.extend(issues)
+                if not issues:
+                    checks_passed += 1
+                logger.info(
+                    "Check '%s': %s (%d issue(s))",
+                    check_name,
+                    "PASS" if not issues else "FAIL",
+                    len(issues),
+                )
+            except Exception as exc:
+                all_issues.append(
+                    ValidationIssue(
+                        check=check_name,
+                        table="",
+                        column=None,
+                        message=f"Check raised unexpected error: {exc}",
+                        severity="error",
+                    )
+                )
+                logger.error("Check '%s' raised an exception: %s", check_name, exc)
+
+        report = ValidationReport(
+            timestamp=datetime.now(timezone.utc),
+            passed=len(all_issues) == 0,
+            issues=all_issues,
+            checks_run=checks_run,
+            checks_passed=checks_passed,
+        )
+
+        logger.info(
+            "Validation complete: %d/%d checks passed, %d total issue(s)",
+            checks_passed,
+            checks_run,
+            len(all_issues),
+        )
+
+        return report
+
+    def write_report(self, report: ValidationReport, output_path: Path) -> None:
+        """Write a markdown validation report to the specified path.
+
+        Creates parent directories if they don't exist. The report includes
+        a timestamp, overall pass/fail status, and details for each issue.
+
+        Args:
+            report: The ValidationReport to write.
+            output_path: Path where the markdown report will be written.
+        """
+        output_path = Path(output_path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        lines: list[str] = []
+        lines.append("# Dataset Validation Report")
+        lines.append("")
+        lines.append(f"**Timestamp:** {report.timestamp.isoformat()}")
+        lines.append(f"**Status:** {'PASSED ✓' if report.passed else 'FAILED ✗'}")
+        lines.append(f"**Checks Run:** {report.checks_run}")
+        lines.append(f"**Checks Passed:** {report.checks_passed}")
+        lines.append(f"**Total Issues:** {len(report.issues)}")
+        lines.append("")
+
+        # Summary table of checks
+        lines.append("## Check Summary")
+        lines.append("")
+        lines.append("| Check | Status |")
+        lines.append("|-------|--------|")
+
+        check_names = [
+            "table_presence",
+            "row_count",
+            "null_check",
+            "foreign_key",
+            "split_presence",
+            "target_labels",
+        ]
+        check_display = {
+            "table_presence": "Table Presence",
+            "row_count": "Row Counts",
+            "null_check": "Null Values",
+            "foreign_key": "Foreign Keys",
+            "split_presence": "Split Presence",
+            "target_labels": "Target Labels",
+        }
+
+        failed_checks = {issue.check for issue in report.issues}
+        for check in check_names:
+            status = "✗ FAIL" if check in failed_checks else "✓ PASS"
+            display = check_display.get(check, check)
+            lines.append(f"| {display} | {status} |")
+
+        lines.append("")
+
+        if report.issues:
+            lines.append("## Issues")
+            lines.append("")
+            for i, issue in enumerate(report.issues, 1):
+                col_info = f" (column: `{issue.column}`)" if issue.column else ""
+                lines.append(
+                    f"{i}. **[{issue.severity.upper()}]** `{issue.table}`{col_info}: "
+                    f"{issue.message}"
+                )
+            lines.append("")
+        else:
+            lines.append("## Result")
+            lines.append("")
+            lines.append("All validation checks passed. Dataset is ready for use.")
+            lines.append("")
+
+        content = "\n".join(lines)
+        output_path.write_text(content, encoding="utf-8")
+        logger.info("Validation report written to %s", output_path)

app/app/main.py

@@ -0,0 +1,200 @@
+"""FastAPI application entry point.
+
+Configures the app instance, middleware, exception handlers, and startup hooks.
+Launch with: uvicorn app.main:app
+"""
+
+import logging
+import uuid
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from app.api.v2.answer_evaluation import router as answer_evaluation_router
+from app.api.v2.bloom import router as bloom_router
+from app.api.v2.class_insights import router as class_insights_router
+from app.api.v2.dependencies import ServiceContainer
+from app.api.v2.health import router as health_router
+from app.api.v2.lo_tagging import router as lo_tagging_router
+from app.api.v2.mastery import router as mastery_router
+from app.api.v2.monitoring import router as monitoring_router
+from app.api.v2.recommendations import router as recommendations_router
+from app.api.v2.risk import router as risk_router
+from app.api.v2.student_profile import router as student_profile_router
+from app.api.v2.teacher_feedback import router as teacher_feedback_router
+from app.core.config import settings
+from app.core.exceptions import DatasetError, EntityNotFoundError, ModelNotLoadedError
+from app.data.loader import DatasetLoader
+from app.models.registry import ModelRegistry
+from app.monitoring.prediction_logger import PredictionLogger
+from app.services.answer_evaluation_service import AnswerEvaluationService
+from app.services.bloom_service import BloomService
+from app.services.class_insights_service import ClassInsightsService
+from app.services.explanation_service import ExplanationService
+from app.services.lo_tagging_service import LOTaggingService
+from app.services.mastery_service import MasteryService
+from app.services.monitoring_service import MonitoringService
+from app.services.recommendation_service import RecommendationService
+from app.services.risk_service import RiskService
+from app.services.student_profile_service import StudentProfileService
+from app.services.teacher_feedback_service import TeacherFeedbackService
+
+logger = logging.getLogger(__name__)
+
+# Internal development origins — no wildcard "*" in production.
+ALLOWED_ORIGINS = [
+    "http://localhost:3000",
+    "http://localhost:8000",
+]
+
+
+def _cache_dataset_metadata(app: FastAPI) -> None:
+    """Load and cache dataset metadata for the data summary endpoint."""
+    try:
+        loader = DatasetLoader(settings.dataset_dir)
+        metadata = loader.load_metadata()
+
+        table_counts: dict[str, int] = metadata.get("table_counts", {})
+
+        app.state.dataset_metadata = {
+            "version": metadata.get("version", "unknown"),
+            "table_counts": table_counts,
+            "validation_status": "not_run",
+            "total_issues": 0,
+        }
+        logger.info("Dataset metadata cached successfully — %d tables", len(table_counts))
+    except DatasetError as exc:
+        logger.warning("Failed to cache dataset metadata: %s", exc)
+        app.state.dataset_metadata = {
+            "version": "unknown",
+            "table_counts": {},
+            "validation_status": "not_run",
+            "total_issues": 0,
+        }
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan: startup and shutdown hooks."""
+    # 1. Cache dataset metadata (existing)
+    _cache_dataset_metadata(app)
+
+    # 2. Initialize model registry and load all models
+    registry = ModelRegistry(settings.model_artifact_dir)
+    registry.load_all()
+
+    # 3. Initialize shared components
+    loader = DatasetLoader(settings.dataset_dir)
+    explainer = ExplanationService()
+    pred_logger = PredictionLogger(
+        log_dir=Path(settings.metrics_dir),
+        salt=settings.log_salt,
+    )
+
+    # 4. Initialize service container with DI
+    app.state.services = ServiceContainer(
+        registry=registry,
+        loader=loader,
+        explainer=explainer,
+        pred_logger=pred_logger,
+        lo_tagging=LOTaggingService(registry, loader, explainer, pred_logger),
+        bloom=BloomService(registry, loader, explainer, pred_logger),
+        mastery=MasteryService(registry, loader, explainer, pred_logger),
+        risk=RiskService(registry, loader, explainer, pred_logger),
+        recommendation=RecommendationService(registry, loader, explainer, pred_logger),
+        answer_evaluation=AnswerEvaluationService(registry, loader, explainer, pred_logger),
+        student_profile=StudentProfileService(loader),
+        class_insights=ClassInsightsService(loader),
+        teacher_feedback=TeacherFeedbackService(),
+        monitoring=MonitoringService(registry, pred_logger),
+    )
+
+    logger.info("Service container initialized — model registry and shared components ready")
+
+    yield
+
+
+app = FastAPI(
+    title=settings.ai_service_name,
+    version=settings.ai_service_version,
+    lifespan=lifespan,
+)
+
+# CORS middleware — internal origins only, no wildcard "*".
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(health_router)
+app.include_router(lo_tagging_router)
+app.include_router(bloom_router)
+app.include_router(mastery_router)
+app.include_router(risk_router)
+app.include_router(recommendations_router)
+app.include_router(answer_evaluation_router)
+app.include_router(student_profile_router)
+app.include_router(class_insights_router)
+app.include_router(teacher_feedback_router)
+app.include_router(monitoring_router)
+
+
+# --- Exception Handlers ---
+
+
+@app.exception_handler(DatasetError)
+async def dataset_error_handler(request: Request, exc: DatasetError) -> JSONResponse:
+    """Handle DatasetError — returns 500 with INTERNAL error code."""
+    request_id = str(uuid.uuid4())
+    logger.error("DatasetError [request_id=%s]: %s", request_id, exc)
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": {
+                "code": "INTERNAL",
+                "message": str(exc),
+                "request_id": request_id,
+            }
+        },
+    )
+
+
+@app.exception_handler(ModelNotLoadedError)
+async def model_not_loaded_handler(request: Request, exc: ModelNotLoadedError) -> JSONResponse:
+    """Handle ModelNotLoadedError — returns 503 with MODEL_NOT_LOADED error code."""
+    request_id = str(uuid.uuid4())
+    logger.error("ModelNotLoadedError [request_id=%s]: %s", request_id, exc)
+    return JSONResponse(
+        status_code=503,
+        content={
+            "error": {
+                "code": "MODEL_NOT_LOADED",
+                "message": str(exc),
+                "request_id": request_id,
+            }
+        },
+    )
+
+
+@app.exception_handler(EntityNotFoundError)
+async def entity_not_found_handler(request: Request, exc: EntityNotFoundError) -> JSONResponse:
+    """Handle EntityNotFoundError — returns 404 with NOT_FOUND error code."""
+    request_id = str(uuid.uuid4())
+    logger.warning("EntityNotFoundError [request_id=%s]: %s", request_id, exc)
+    return JSONResponse(
+        status_code=404,
+        content={
+            "error": {
+                "code": "NOT_FOUND",
+                "message": str(exc),
+                "request_id": request_id,
+            }
+        },
+    )

app/app/models/__init__.py

@@ -0,0 +1,5 @@
+"""Models package — model registry and artifact management."""
+
+from app.models.registry import ModelRegistry, REGISTERED_MODELS
+
+__all__ = ["ModelRegistry", "REGISTERED_MODELS"]

app/app/models/registry.py

@@ -0,0 +1,156 @@
+"""Model Registry for loading, caching, and serving trained model artifacts.
+
+Supports eager loading at startup and lazy loading on first access.
+Reports per-model health status.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+import joblib
+
+from app.core.exceptions import ModelNotLoadedError
+
+logger = logging.getLogger(__name__)
+
+# All registered model names and their artifact subdirectory names
+REGISTERED_MODELS: list[str] = [
+    "lo_tagger",
+    "bloom_classifier",
+    "mastery_model",
+    "risk_model",
+    "answer_scorer",
+    "recommender",
+]
+
+
+class ModelRegistry:
+    """Loads and manages trained model artifacts.
+
+    Supports eager loading at startup and lazy loading on first access.
+    Reports per-model health status.
+    """
+
+    def __init__(self, artifact_dir: str | Path) -> None:
+        self._artifact_dir = Path(artifact_dir)
+        self._models: dict[str, dict[str, Any]] = {}
+        self._status: dict[str, str] = {}  # "loaded" | "not_loaded" | "error"
+        self._metadata: dict[str, dict] = {}  # metrics.json content per model
+
+        # Initialize all registered models as not_loaded
+        for model_name in REGISTERED_MODELS:
+            self._status[model_name] = "not_loaded"
+
+    def load_all(self) -> None:
+        """Eagerly load all model artifacts from artifact_dir subdirectories."""
+        for model_name in REGISTERED_MODELS:
+            self._load_model(model_name)
+
+    def _load_model(self, model_name: str) -> None:
+        """Load a single model's artifacts from its subdirectory.
+
+        On failure, sets status to 'error' and logs the exception without crashing.
+        """
+        model_dir = self._artifact_dir / model_name
+
+        if not model_dir.exists():
+            logger.warning(
+                "Model directory not found for '%s': %s", model_name, model_dir
+            )
+            self._status[model_name] = "not_loaded"
+            return
+
+        try:
+            model_data: dict[str, Any] = {}
+
+            # Required: model.joblib
+            model_path = model_dir / "model.joblib"
+            if not model_path.exists():
+                logger.warning(
+                    "model.joblib not found for '%s' at %s", model_name, model_path
+                )
+                self._status[model_name] = "not_loaded"
+                return
+
+            model_data["model"] = joblib.load(model_path)
+
+            # Optional: vectorizer.joblib
+            vectorizer_path = model_dir / "vectorizer.joblib"
+            if vectorizer_path.exists():
+                model_data["vectorizer"] = joblib.load(vectorizer_path)
+
+            # Optional: label_encoder.joblib
+            label_encoder_path = model_dir / "label_encoder.joblib"
+            if label_encoder_path.exists():
+                model_data["label_encoder"] = joblib.load(label_encoder_path)
+
+            # Optional: feature_columns.json
+            feature_columns_path = model_dir / "feature_columns.json"
+            if feature_columns_path.exists():
+                with open(feature_columns_path, "r", encoding="utf-8") as f:
+                    model_data["feature_columns"] = json.load(f)
+
+            # Optional: metrics.json (stored as metadata)
+            metrics_path = model_dir / "metrics.json"
+            if metrics_path.exists():
+                with open(metrics_path, "r", encoding="utf-8") as f:
+                    self._metadata[model_name] = json.load(f)
+
+            self._models[model_name] = model_data
+            self._status[model_name] = "loaded"
+            logger.info("Model '%s' loaded successfully from %s", model_name, model_dir)
+
+        except Exception:
+            logger.exception("Failed to load model '%s' from %s", model_name, model_dir)
+            self._status[model_name] = "error"
+
+    def get_model(self, model_name: str) -> dict[str, Any]:
+        """Retrieve a loaded model by name. Triggers lazy load if not yet loaded.
+
+        Returns a dict containing 'model' and optional 'vectorizer',
+        'label_encoder', 'feature_columns' keys.
+
+        Raises ModelNotLoadedError if artifact is missing/corrupted after load attempt.
+        """
+        if model_name not in self._status:
+            raise ModelNotLoadedError(
+                f"Model '{model_name}' is not registered in the registry."
+            )
+
+        # Lazy loading: attempt to load if not yet loaded
+        if self._status[model_name] == "not_loaded":
+            self._load_model(model_name)
+
+        if self._status[model_name] != "loaded":
+            raise ModelNotLoadedError(
+                f"Model '{model_name}' is not available (status: {self._status[model_name]})."
+            )
+
+        return self._models[model_name]
+
+    def get_status(self, model_name: str) -> str:
+        """Return 'loaded', 'not_loaded', or 'error' for a given model."""
+        return self._status.get(model_name, "not_loaded")
+
+    def get_metadata(self, model_name: str) -> dict | None:
+        """Return metrics.json content for a model, or None if not available."""
+        return self._metadata.get(model_name)
+
+    def get_all_status(self) -> dict[str, dict]:
+        """Return status + metadata for all registered models."""
+        result: dict[str, dict] = {}
+        for model_name in REGISTERED_MODELS:
+            entry: dict[str, Any] = {
+                "status": self._status.get(model_name, "not_loaded"),
+            }
+            metadata = self._metadata.get(model_name)
+            if metadata:
+                entry["metadata"] = metadata
+            result[model_name] = entry
+        return result
+
+    def is_loaded(self, model_name: str) -> bool:
+        """Check if a model is loaded and ready for inference."""
+        return self._status.get(model_name) == "loaded"

app/app/monitoring/__init__.py

@@ -0,0 +1,5 @@
+# Monitoring package
+
+from app.monitoring.prediction_logger import PredictionLogger
+
+__all__ = ["PredictionLogger"]

app/app/monitoring/prediction_logger.py

@@ -0,0 +1,137 @@
+"""Prediction logger for monitoring and drift detection.
+
+Logs every prediction to a JSONL file with anonymized student IDs.
+Logging is synchronous but lightweight (append to file).
+"""
+
+import hashlib
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Fields that must never appear in prediction logs (PII protection)
+_PII_FIELDS = {"student_name", "student_answer", "parent_contact"}
+
+
+class PredictionLogger:
+    """Logs predictions to JSONL for monitoring and drift detection.
+
+    Logging is synchronous but lightweight (append to file).
+    Student IDs are anonymized via stable hash before logging.
+    """
+
+    def __init__(self, log_dir: Path, salt: str) -> None:
+        self._log_dir = Path(log_dir)
+        self._log_dir.mkdir(parents=True, exist_ok=True)
+        self._log_path = self._log_dir / "prediction_logs.jsonl"
+        self._salt = salt
+
+    def log(
+        self,
+        prediction_id: str,
+        model_name: str,
+        model_version: str,
+        endpoint: str,
+        input_summary: dict,
+        output: dict,
+        source: str,
+        latency_ms: float,
+    ) -> None:
+        """Append a prediction log entry. Non-blocking, fire-and-forget."""
+        try:
+            # Anonymize student_id in input_summary if present
+            safe_input = self._sanitize_input_summary(input_summary)
+
+            entry = {
+                "prediction_id": prediction_id,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "model_name": model_name,
+                "model_version": model_version,
+                "endpoint": endpoint,
+                "input_summary": safe_input,
+                "output": output,
+                "source": source,
+                "latency_ms": latency_ms,
+            }
+
+            with open(self._log_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry) + "\n")
+
+        except Exception:
+            # Fire-and-forget: never let logging failures propagate
+            logger.exception("Failed to write prediction log entry")
+
+    def _anonymize_student_id(self, student_id: str) -> str:
+        """SHA-256 hash with salt, truncated to 16 chars."""
+        return hashlib.sha256(
+            f"{self._salt}:{student_id}".encode()
+        ).hexdigest()[:16]
+
+    def _sanitize_input_summary(self, input_summary: dict) -> dict:
+        """Remove PII fields and anonymize student_id in input summary."""
+        safe = {}
+        for key, value in input_summary.items():
+            if key in _PII_FIELDS:
+                continue
+            if key == "student_id" and isinstance(value, str):
+                safe["student_id"] = self._anonymize_student_id(value)
+            else:
+                safe[key] = value
+        return safe
+
+    def get_recent_stats(self, model_name: str, hours: int = 24) -> dict:
+        """Return prediction count and avg confidence for last N hours."""
+        count = 0
+        total_confidence = 0.0
+
+        if not self._log_path.exists():
+            return {"prediction_count": 0, "avg_confidence": None}
+
+        cutoff = datetime.now(timezone.utc).timestamp() - (hours * 3600)
+
+        try:
+            with open(self._log_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        entry = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+
+                    if entry.get("model_name") != model_name:
+                        continue
+
+                    # Parse timestamp and check if within window
+                    ts_str = entry.get("timestamp", "")
+                    try:
+                        ts = datetime.fromisoformat(ts_str).timestamp()
+                    except (ValueError, TypeError):
+                        continue
+
+                    if ts < cutoff:
+                        continue
+
+                    count += 1
+                    # Extract confidence from output
+                    output = entry.get("output", {})
+                    confidence = output.get("confidence")
+                    if confidence is not None:
+                        try:
+                            total_confidence += float(confidence)
+                        except (ValueError, TypeError):
+                            pass
+
+        except Exception:
+            logger.exception("Failed to read prediction log for stats")
+            return {"prediction_count": 0, "avg_confidence": None}
+
+        avg_confidence = (total_confidence / count) if count > 0 else None
+        return {
+            "prediction_count": count,
+            "avg_confidence": avg_confidence,
+        }

app/app/schemas/__init__.py

@@ -0,0 +1 @@
+# Schemas package

app/app/schemas/answer_evaluation.py

@@ -0,0 +1,36 @@
+"""Pydantic schemas for the answer evaluation endpoint."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AnswerEvaluationRequest(BaseModel):
+    """Request model for POST /ai/v2/evaluate-answer."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    question_id: str = Field(..., min_length=1, max_length=50)
+    question_text: str = Field(..., min_length=5, max_length=2000)
+    student_answer: str = Field(..., min_length=1, max_length=5000)
+    model_answer: str = Field(..., min_length=1, max_length=5000)
+    rubric: str = Field(..., min_length=1, max_length=2000)
+    max_marks: int = Field(..., ge=1, le=100)
+    grade: int = Field(..., ge=6, le=8)
+    subject: str
+    lo_id: str = Field(..., min_length=1, max_length=50)
+    bloom_level: str
+
+
+class AnswerEvaluationResponse(BaseModel):
+    """Response model for POST /ai/v2/evaluate-answer."""
+
+    prediction_id: str
+    model_version: str
+    source: str
+    confidence: float = Field(..., ge=0.0, le=1.0)
+    timestamp: str
+    predicted_marks: float = Field(..., ge=0.0)
+    max_marks: int
+    concepts_covered: list[str]
+    missing_points: list[str]
+    feedback: str
+    teacher_review_required: bool  # always True in V2

app/app/schemas/bloom.py

@@ -0,0 +1,29 @@
+"""Pydantic schemas for the Bloom classification endpoint.
+
+POST /ai/v2/classify-bloom
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BloomRequest(BaseModel):
+    """Request model for Bloom taxonomy classification."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    question_text: str = Field(..., min_length=5, max_length=2000)
+    grade: int = Field(..., ge=6, le=8)
+    subject: str
+    question_type: str = Field(..., min_length=1, max_length=50)
+
+
+class BloomResponse(BaseModel):
+    """Response model for Bloom taxonomy classification."""
+
+    prediction_id: str
+    model_version: str
+    source: str  # "model" | "fallback_rule_based"
+    confidence: float = Field(..., ge=0.0, le=1.0)
+    timestamp: str
+    bloom_level: str  # one of BLOOM_LEVELS
+    reason: str

app/app/schemas/class_insights.py

@@ -0,0 +1,34 @@
+"""Pydantic schemas for the class insights endpoint."""
+
+from pydantic import BaseModel, Field
+
+
+class WeakLOItem(BaseModel):
+    """A single weak learning outcome entry in class insights."""
+
+    lo_id: str
+    title: str
+    average_mastery: float = Field(..., ge=0.0, le=1.0)
+    affected_students_count: int = Field(..., ge=0)
+
+
+class InterventionItem(BaseModel):
+    """A recommended intervention for a group of students."""
+
+    type: str
+    reason: str
+    students: list[str]  # student_id list only, NO names
+
+
+class ClassInsightsResponse(BaseModel):
+    """Response model for GET /ai/v2/class-insights/{class_id}."""
+
+    class_id: str
+    subject: str | None
+    model_version: str
+    timestamp: str
+    weakest_learning_outcomes: list[WeakLOItem]
+    at_risk_students_count: int = Field(..., ge=0)
+    at_risk_students: list[str]  # student_id only
+    recommended_interventions: list[InterventionItem]
+    lesson_plan_suggestion: str | None

app/app/schemas/health.py

@@ -0,0 +1,43 @@
+"""Pydantic response schemas for health and data summary endpoints."""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class HealthResponse(BaseModel):
+    """Response model for GET /ai/v2/health."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: str
+    service: str
+    version: str
+    models_loaded: bool
+
+
+class DataSummaryResponse(BaseModel):
+    """Response model for GET /ai/v2/data/summary."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    dataset_version: str
+    table_counts: dict[str, int]
+    validation_status: str
+    total_issues: int
+
+
+class ErrorDetail(BaseModel):
+    """Detail object within the error envelope."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    code: str
+    message: str
+    request_id: str
+
+
+class ErrorResponse(BaseModel):
+    """Standard error envelope for all API error responses."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    error: ErrorDetail