Production-ready API with logging, validation, and docs

app.py

@@ -1,19 +1,35 @@
-from typing import List, Optional
+"""
+Learning Objective Taxonomy API
+FastAPI backend for Bloom's, Dave's, and CO-PO analysis
+"""
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional
 
 import numpy as np
 from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from sentence_transformers import SentenceTransformer
-from transformers import pipeline
+from transformers import Pipeline, pipeline
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
 
+# FastAPI app
 app = FastAPI(
     title="Learning Objective Taxonomy API",
-    description="API for Bloom's, Dave's, and CO-PO analysis",
+    description="API for Bloom's Taxonomy, Dave's Psychomotor, and CO-PO Mapping analysis",
     version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
 )
 
-# CORS middleware for Next.js
+# CORS middleware
 app.add_middleware(
     CORSMiddleware,
     allow_origins=["*"],
@@ -22,39 +38,174 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
-# Load your models at startup
-print("Loading models...")
-try:
-    blooms_model = pipeline("text-classification", model="Jrine/blooms")
-    dave_model = pipeline("text-classification", model="Jrine/dave")
-    coppo_model = SentenceTransformer("Jrine/co-po")
-    print("✅ All models loaded successfully!")
-except Exception as e:
-    print(f"❌ Error loading models: {e}")
-    blooms_model = None
-    dave_model = None
-    coppo_model = None
+# Global model variables
+blooms_model: Optional[Pipeline] = None
+dave_model: Optional[Pipeline] = None
+coppo_model: Optional[SentenceTransformer] = None
 
 
 # Pydantic models
 class TextRequest(BaseModel):
+    text: str = Field(
+        ...,
+        min_length=1,
+        max_length=1000,
+        description="Learning objective text to analyze",
+    )
+
+
+class PredictionResult(BaseModel):
+    level: Optional[str] = Field(None, description="Predicted taxonomy level")
+    confidence: Optional[float] = Field(None, description="Confidence score (0-1)")
+    all_predictions: List[Dict[str, Any]] = Field(
+        default_factory=list, description="All prediction results"
+    )
+
+
+class SingleModelResponse(BaseModel):
+    success: bool
+    model: str
     text: str
+    prediction: PredictionResult
+    timestamp: str
 
 
-class AnalyzeAllRequest(BaseModel):
+class EmbeddingResponse(BaseModel):
+    success: bool
+    model: str
     text: str
+    embeddings: List[float]
+    timestamp: str
+
+
+class CombinedResults(BaseModel):
+    blooms: Dict[str, Any]
+    dave: Dict[str, Any]
+    coppo: Dict[str, Any]
+
+
+class CombinedResponse(BaseModel):
+    success: bool
+    text: str
+    results: CombinedResults
+    timestamp: str
+
+
+class HealthResponse(BaseModel):
+    status: str
+    models_loaded: Dict[str, bool]
+
+
+# Helper functions
+def normalize_results(results: Any) -> List[Dict[str, Any]]:
+    """Normalize various model output formats to list of dicts."""
+    if isinstance(results, list):
+        return [
+            item if isinstance(item, dict) else {"label": str(item)} for item in results
+        ]
+
+    if isinstance(results, dict):
+        return [results]
+
+    if isinstance(results, np.ndarray):
+        try:
+            return [{"value": item.tolist()} for item in results]
+        except Exception:
+            return [{"value": results.tolist()}]
+
+    try:
+        candidate = list(results)
+        return [
+            item if isinstance(item, dict) else {"label": str(item)}
+            for item in candidate
+        ]
+    except (TypeError, AttributeError):
+        return [{"value": results}]
+
+
+def extract_label_and_score(results: List[Dict[str, Any]]) -> Dict[str, Optional[Any]]:
+    """Extract label and score from normalized results with fallback."""
+    if not results:
+        return {"label": None, "score": None}
+
+    first = results[0]
+    label = first.get("label")
+    score = first.get("score") or first.get("confidence")
+
+    try:
+        score = float(score) if score is not None else None
+    except (ValueError, TypeError):
+        score = None
 
+    return {"label": label, "score": score}
 
-@app.get("/")
+
+def get_timestamp() -> str:
+    """Get current UTC timestamp in ISO format."""
+    return datetime.utcnow().isoformat() + "Z"
+
+
+# Model loading at startup
+@app.on_event("startup")
+async def load_models():
+    """Load all models at application startup."""
+    global blooms_model, dave_model, coppo_model
+
+    logger.info("=" * 60)
+    logger.info("Starting model loading...")
+    logger.info("=" * 60)
+
+    # Load Bloom's model
+    try:
+        logger.info("Loading Bloom's Taxonomy model (Jrine/blooms)...")
+        blooms_model = pipeline("text-classification", model="Jrine/blooms")
+        logger.info("✅ Bloom's model loaded successfully")
+    except Exception as e:
+        logger.error(f"❌ Failed to load Bloom's model: {e}")
+        blooms_model = None
+
+    # Load Dave's model
+    try:
+        logger.info("Loading Dave's Psychomotor model (Jrine/dave)...")
+        dave_model = pipeline("text-classification", model="Jrine/dave")
+        logger.info("✅ Dave's model loaded successfully")
+    except Exception as e:
+        logger.error(f"❌ Failed to load Dave's model: {e}")
+        dave_model = None
+
+    # Load CO-PO model
+    try:
+        logger.info("Loading CO-PO mapping model (Jrine/co-po)...")
+        coppo_model = SentenceTransformer("Jrine/co-po")
+        logger.info("✅ CO-PO model loaded successfully")
+    except Exception as e:
+        logger.error(f"❌ Failed to load CO-PO model: {e}")
+        coppo_model = None
+
+    logger.info("=" * 60)
+    logger.info(
+        f"Model loading complete - "
+        f"Bloom's: {blooms_model is not None}, "
+        f"Dave's: {dave_model is not None}, "
+        f"CO-PO: {coppo_model is not None}"
+    )
+    logger.info("=" * 60)
+
+
+# API Endpoints
+@app.get("/", tags=["Root"])
 async def root():
+    """API root endpoint with status information."""
     return {
         "message": "Learning Objective Taxonomy API",
         "version": "1.0.0",
+        "documentation": "/docs",
         "endpoints": {
             "blooms": "/api/blooms",
             "dave": "/api/dave",
             "coppo": "/api/coppo",
             "analyze": "/api/analyze",
+            "health": "/health",
         },
         "status": {
             "blooms": blooms_model is not None,
@@ -64,111 +215,188 @@ async def root():
     }
 
 
-@app.post("/api/blooms")
+@app.post(
+    "/api/blooms",
+    response_model=SingleModelResponse,
+    tags=["Classification"],
+    summary="Classify Bloom's Taxonomy Level",
+    description="Classifies learning objectives into Bloom's 6 cognitive levels: Remember, Understand, Apply, Analyze, Evaluate, Create",
+)
 async def predict_blooms(request: TextRequest):
+    """Predict Bloom's Taxonomy cognitive level for a learning objective."""
     if blooms_model is None:
-        raise HTTPException(status_code=503, detail="Blooms model not loaded")
+        logger.error("Bloom's model not available")
+        raise HTTPException(status_code=503, detail="Bloom's model not loaded")
 
     try:
-        results = blooms_model(request.text)
+        logger.info(f"Bloom's prediction for: {request.text[:50]}...")
+        raw = blooms_model(request.text)
+        results = normalize_results(raw)
+        first = extract_label_and_score(results)
 
         return {
             "success": True,
             "model": "blooms-taxonomy",
             "text": request.text,
             "prediction": {
-                "level": results[0]["label"],
-                "confidence": results[0]["score"],
+                "level": first["label"],
+                "confidence": first["score"],
                 "all_predictions": results,
             },
-            "timestamp": None,
+            "timestamp": get_timestamp(),
         }
     except Exception as e:
+        logger.error(f"Bloom's prediction error: {e}")
         raise HTTPException(status_code=500, detail=str(e))
 
 
-@app.post("/api/dave")
+@app.post(
+    "/api/dave",
+    response_model=SingleModelResponse,
+    tags=["Classification"],
+    summary="Classify Dave's Psychomotor Level",
+    description="Classifies learning objectives into Dave's 5 psychomotor levels: Imitation, Manipulation, Precision, Articulation, Naturalization",
+)
 async def predict_dave(request: TextRequest):
+    """Predict Dave's Psychomotor motor skill level for a learning objective."""
     if dave_model is None:
-        raise HTTPException(status_code=503, detail="Dave model not loaded")
+        logger.error("Dave's model not available")
+        raise HTTPException(status_code=503, detail="Dave's model not loaded")
 
     try:
-        results = dave_model(request.text)
+        logger.info(f"Dave's prediction for: {request.text[:50]}...")
+        raw = dave_model(request.text)
+        results = normalize_results(raw)
+        first = extract_label_and_score(results)
 
         return {
             "success": True,
             "model": "dave-psychomotor",
             "text": request.text,
             "prediction": {
-                "level": results[0]["label"],
-                "confidence": results[0]["score"],
+                "level": first["label"],
+                "confidence": first["score"],
                 "all_predictions": results,
             },
-            "timestamp": None,
+            "timestamp": get_timestamp(),
         }
     except Exception as e:
+        logger.error(f"Dave's prediction error: {e}")
         raise HTTPException(status_code=500, detail=str(e))
 
 
-@app.post("/api/coppo")
+@app.post(
+    "/api/coppo",
+    response_model=EmbeddingResponse,
+    tags=["Embeddings"],
+    summary="Generate CO-PO Embeddings",
+    description="Generates semantic embeddings for Course Outcome to Program Outcome mapping",
+)
 async def predict_coppo(request: TextRequest):
+    """Generate CO-PO semantic embeddings for a course outcome."""
     if coppo_model is None:
+        logger.error("CO-PO model not available")
         raise HTTPException(status_code=503, detail="CO-PO model not loaded")
 
     try:
+        logger.info(f"CO-PO embedding for: {request.text[:50]}...")
         embeddings = coppo_model.encode(request.text)
 
+        if isinstance(embeddings, np.ndarray):
+            emb_list = embeddings.tolist()
+        else:
+            emb_list = (
+                list(embeddings)
+                if hasattr(embeddings, "__iter__")
+                else [float(embeddings)]
+            )
+
         return {
             "success": True,
             "model": "co-po",
             "text": request.text,
-            "embeddings": embeddings.tolist(),
-            "timestamp": None,
+            "embeddings": emb_list,
+            "timestamp": get_timestamp(),
         }
     except Exception as e:
+        logger.error(f"CO-PO embedding error: {e}")
         raise HTTPException(status_code=500, detail=str(e))
 
 
-@app.post("/api/analyze")
-async def analyze_all(request: AnalyzeAllRequest):
+@app.post(
+    "/api/analyze",
+    response_model=CombinedResponse,
+    tags=["Combined Analysis"],
+    summary="Analyze with All Models",
+    description="Runs all three models (Bloom's, Dave's, CO-PO) on the input text and returns combined results",
+)
+async def analyze_all(request: TextRequest):
+    """Analyze learning objective with all three models simultaneously."""
     if not all([blooms_model, dave_model, coppo_model]):
+        logger.error("Not all models available for combined analysis")
         raise HTTPException(status_code=503, detail="Not all models loaded")
 
     try:
+        logger.info(f"Combined analysis for: {request.text[:50]}...")
+
         # Run all models
-        blooms_results = blooms_model(request.text)
-        dave_results = dave_model(request.text)
+        raw_blooms = blooms_model(request.text)
+        raw_dave = dave_model(request.text)
         coppo_embeddings = coppo_model.encode(request.text)
 
+        # Process results
+        blooms_results = normalize_results(raw_blooms)
+        dave_results = normalize_results(raw_dave)
+        first_blooms = extract_label_and_score(blooms_results)
+        first_dave = extract_label_and_score(dave_results)
+
+        # Convert embeddings
+        if isinstance(coppo_embeddings, np.ndarray):
+            emb_list = coppo_embeddings.tolist()
+        else:
+            emb_list = (
+                list(coppo_embeddings)
+                if hasattr(coppo_embeddings, "__iter__")
+                else [float(coppo_embeddings)]
+            )
+
         return {
             "success": True,
             "text": request.text,
             "results": {
                 "blooms": {
-                    "level": blooms_results[0]["label"],
-                    "confidence": blooms_results[0]["score"],
+                    "level": first_blooms["label"],
+                    "confidence": first_blooms["score"],
                     "all_predictions": blooms_results,
                     "model": "Jrine/blooms",
                 },
                 "dave": {
-                    "level": dave_results[0]["label"],
-                    "confidence": dave_results[0]["score"],
+                    "level": first_dave["label"],
+                    "confidence": first_dave["score"],
                     "all_predictions": dave_results,
                     "model": "Jrine/dave",
                 },
                 "coppo": {
-                    "embeddings": coppo_embeddings.tolist(),
+                    "embeddings": emb_list,
                     "model": "Jrine/co-po",
                 },
             },
-            "timestamp": None,
+            "timestamp": get_timestamp(),
         }
     except Exception as e:
+        logger.error(f"Combined analysis error: {e}")
         raise HTTPException(status_code=500, detail=str(e))
 
 
-@app.get("/health")
+@app.get(
+    "/health",
+    response_model=HealthResponse,
+    tags=["Health"],
+    summary="Health Check",
+    description="Returns API health status and model availability",
+)
 async def health():
+    """Health check endpoint for monitoring."""
     return {
         "status": "healthy",
         "models_loaded": {
@@ -182,4 +410,4 @@ async def health():
 if __name__ == "__main__":
     import uvicorn
 
-    uvicorn.run(app, host="0.0.0.0", port=7860)
+    uvicorn.run(app, host="0.0.0.0", port=7860, log_level="info")