Add knowledge graph and adaptive learning path features to HF Space

app/api/v2/dependencies.py

@@ -41,6 +41,8 @@ class ServiceContainer:
     class_insights: Any = None
     teacher_feedback: Any = None
     monitoring: Any = None
+    knowledge_graph: Any = None
+    adaptive_learning_path: Any = None
 
 
 def get_service_container(request: Request) -> ServiceContainer:
@@ -96,3 +98,13 @@ def get_teacher_feedback_service(request: Request) -> Any:
 def get_monitoring_service(request: Request) -> Any:
     """Provide the monitoring service instance."""
     return request.app.state.services.monitoring
+
+
+def get_knowledge_graph_service(request: Request) -> Any:
+    """Provide the knowledge graph service instance."""
+    return request.app.state.services.knowledge_graph
+
+
+def get_adaptive_learning_path_service(request: Request) -> Any:
+    """Provide the adaptive learning path service instance."""
+    return request.app.state.services.adaptive_learning_path

app/api/v2/knowledge_graph.py

@@ -0,0 +1,122 @@
+"""Knowledge graph API endpoints."""
+
+import logging
+from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi.responses import JSONResponse
+
+from app.core.exceptions import EntityNotFoundError, DatasetError
+from app.schemas.knowledge_graph import KnowledgeGraphResponse
+from app.services.knowledge_graph_service import KnowledgeGraphService
+from app.api.v2.dependencies import get_knowledge_graph_service
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/ai/v2/knowledge-graph", tags=["knowledge-graph"])
+
+
+# NOTE: Static-segment routes MUST be declared before dynamic /{lo_id} routes
+# so FastAPI doesn't swallow "path" as a lo_id value.
+
+
+@router.get(
+    "/path/{start_lo}/{target_lo}",
+    summary="Get shortest path between two learning outcomes",
+    description="Find the shortest dependency path between two learning outcomes in the knowledge graph"
+)
+async def get_learning_path_between_los(
+    start_lo: str,
+    target_lo: str,
+    knowledge_graph_service: KnowledgeGraphService = Depends(get_knowledge_graph_service)
+) -> JSONResponse:
+    """Get learning path between two learning outcomes."""
+    try:
+        path = knowledge_graph_service.get_learning_path(start_lo, target_lo)
+        return JSONResponse(content={
+            "start_lo": start_lo,
+            "target_lo": target_lo,
+            "path": path,
+            "steps": len(path)
+        })
+    except EntityNotFoundError as exc:
+        logger.warning("Learning path query failed - entity not found: %s", exc)
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except Exception as exc:
+        logger.error("Learning path query failed: %s", exc)
+        raise HTTPException(status_code=500, detail="Internal server error") from exc
+
+
+@router.get(
+    "/{lo_id}/prerequisites",
+    summary="Get prerequisites for a learning outcome",
+    description="Get all prerequisite learning outcomes for a given LO"
+)
+async def get_prerequisites(
+    lo_id: str,
+    max_depth: int = Query(default=None, ge=1, le=10, description="Maximum depth to traverse"),
+    knowledge_graph_service: KnowledgeGraphService = Depends(get_knowledge_graph_service)
+) -> JSONResponse:
+    """Get prerequisites for a learning outcome."""
+    try:
+        prerequisites = knowledge_graph_service.get_prerequisites(lo_id, max_depth)
+        return JSONResponse(content={
+            "lo_id": lo_id,
+            "prerequisites": prerequisites,
+            "count": len(prerequisites)
+        })
+    except EntityNotFoundError as exc:
+        logger.warning("Prerequisites query failed - entity not found: %s", exc)
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except Exception as exc:
+        logger.error("Prerequisites query failed: %s", exc)
+        raise HTTPException(status_code=500, detail="Internal server error") from exc
+
+
+@router.get(
+    "/{lo_id}/successors",
+    summary="Get successors for a learning outcome",
+    description="Get all successor learning outcomes for a given LO"
+)
+async def get_successors(
+    lo_id: str,
+    max_depth: int = Query(default=None, ge=1, le=10, description="Maximum depth to traverse"),
+    knowledge_graph_service: KnowledgeGraphService = Depends(get_knowledge_graph_service)
+) -> JSONResponse:
+    """Get successors for a learning outcome."""
+    try:
+        successors = knowledge_graph_service.get_successors(lo_id, max_depth)
+        return JSONResponse(content={
+            "lo_id": lo_id,
+            "successors": successors,
+            "count": len(successors)
+        })
+    except EntityNotFoundError as exc:
+        logger.warning("Successors query failed - entity not found: %s", exc)
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except Exception as exc:
+        logger.error("Successors query failed: %s", exc)
+        raise HTTPException(status_code=500, detail="Internal server error") from exc
+
+
+@router.get(
+    "/{lo_id}",
+    response_model=KnowledgeGraphResponse,
+    summary="Get knowledge graph for a learning outcome",
+    description="Retrieve full knowledge graph info including prerequisites and successors for a learning outcome"
+)
+async def get_knowledge_graph(
+    lo_id: str,
+    max_depth: int = Query(default=2, ge=1, le=5, description="Maximum depth to traverse"),
+    knowledge_graph_service: KnowledgeGraphService = Depends(get_knowledge_graph_service)
+) -> KnowledgeGraphResponse:
+    """Get knowledge graph information for a learning outcome."""
+    try:
+        return knowledge_graph_service.get_knowledge_graph(lo_id, max_depth)
+    except EntityNotFoundError as exc:
+        logger.warning("Knowledge graph query failed - entity not found: %s", exc)
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except DatasetError as exc:
+        logger.error("Knowledge graph query failed - dataset error: %s", exc)
+        raise HTTPException(status_code=503, detail="Knowledge graph service unavailable") from exc
+    except Exception as exc:
+        logger.error("Knowledge graph query failed - unexpected error: %s", exc)
+        raise HTTPException(status_code=500, detail="Internal server error") from exc

app/api/v2/learning_path.py

@@ -0,0 +1,75 @@
+"""Adaptive learning path API endpoints."""
+
+import logging
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from app.core.exceptions import EntityNotFoundError, DatasetError
+from app.schemas.learning_path import LearningPathRequest, LearningPathResponse
+from app.services.adaptive_learning_path_service import AdaptiveLearningPathService
+from app.api.v2.dependencies import get_adaptive_learning_path_service
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/ai/v2/learning-path", tags=["learning-path"])
+
+
+@router.get(
+    "/{student_id}",
+    response_model=LearningPathResponse,
+    summary="Generate adaptive learning path",
+    description="Generate a personalized learning path for a student to reach a target learning outcome"
+)
+async def generate_learning_path(
+    student_id: str,
+    target_lo_id: str = Query(..., description="Target learning outcome ID"),
+    max_steps: int = Query(default=10, ge=1, le=20, description="Maximum number of steps in path"),
+    include_mastered: bool = Query(default=False, description="Include already mastered LOs for review"),
+    difficulty_preference: str = Query(default="adaptive", description="Difficulty preference: easy, medium, hard, adaptive"),
+    learning_path_service: AdaptiveLearningPathService = Depends(get_adaptive_learning_path_service)
+) -> LearningPathResponse:
+    """Generate an adaptive learning path for a student."""
+    try:
+        request = LearningPathRequest(
+            student_id=student_id,
+            target_lo_id=target_lo_id,
+            max_steps=max_steps,
+            include_mastered=include_mastered,
+            difficulty_preference=difficulty_preference
+        )
+        
+        return learning_path_service.generate_learning_path(request)
+        
+    except EntityNotFoundError as exc:
+        logger.warning("Learning path generation failed - entity not found: %s", exc)
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except DatasetError as exc:
+        logger.error("Learning path generation failed - dataset error: %s", exc)
+        raise HTTPException(status_code=503, detail="Learning path service unavailable") from exc
+    except Exception as exc:
+        logger.error("Learning path generation failed - unexpected error: %s", exc)
+        raise HTTPException(status_code=500, detail="Internal server error") from exc
+
+
+@router.post(
+    "/",
+    response_model=LearningPathResponse,
+    summary="Generate adaptive learning path (POST)",
+    description="Generate a personalized learning path using POST request body"
+)
+async def generate_learning_path_post(
+    request: LearningPathRequest,
+    learning_path_service: AdaptiveLearningPathService = Depends(get_adaptive_learning_path_service)
+) -> LearningPathResponse:
+    """Generate an adaptive learning path for a student using POST."""
+    try:
+        return learning_path_service.generate_learning_path(request)
+        
+    except EntityNotFoundError as exc:
+        logger.warning("Learning path generation failed - entity not found: %s", exc)
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except DatasetError as exc:
+        logger.error("Learning path generation failed - dataset error: %s", exc)
+        raise HTTPException(status_code=503, detail="Learning path service unavailable") from exc
+    except Exception as exc:
+        logger.error("Learning path generation failed - unexpected error: %s", exc)
+        raise HTTPException(status_code=500, detail="Internal server error") from exc

app/main.py

@@ -18,6 +18,8 @@ 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.knowledge_graph import router as knowledge_graph_router
+from app.api.v2.learning_path import router as learning_path_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
@@ -31,9 +33,11 @@ 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.adaptive_learning_path_service import AdaptiveLearningPathService
 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.knowledge_graph_service import KnowledgeGraphService
 from app.services.lo_tagging_service import LOTaggingService
 from app.services.mastery_service import MasteryService
 from app.services.monitoring_service import MonitoringService
@@ -96,6 +100,7 @@ async def lifespan(app: FastAPI):
     )
 
     # 4. Initialize service container with DI
+    knowledge_graph_service = KnowledgeGraphService(loader)
     app.state.services = ServiceContainer(
         registry=registry,
         loader=loader,
@@ -111,6 +116,8 @@ async def lifespan(app: FastAPI):
         class_insights=ClassInsightsService(loader),
         teacher_feedback=TeacherFeedbackService(),
         monitoring=MonitoringService(registry, pred_logger),
+        knowledge_graph=knowledge_graph_service,
+        adaptive_learning_path=AdaptiveLearningPathService(loader, knowledge_graph_service),
     )
 
     logger.info("Service container initialized — model registry and shared components ready")
@@ -145,6 +152,8 @@ app.include_router(student_profile_router)
 app.include_router(class_insights_router)
 app.include_router(teacher_feedback_router)
 app.include_router(monitoring_router)
+app.include_router(knowledge_graph_router)
+app.include_router(learning_path_router)
 
 
 # --- Exception Handlers ---

app/schemas/knowledge_graph.py

@@ -0,0 +1,57 @@
+"""Pydantic schemas for knowledge graph endpoints."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class LONode(BaseModel):
+    """A learning outcome node in the knowledge graph."""
+    
+    lo_id: str = Field(..., description="Learning outcome ID")
+    title: str = Field(..., description="Learning outcome title")
+    grade: int = Field(..., ge=6, le=8, description="Grade level")
+    subject: str = Field(..., description="Subject name")
+    chapter: str = Field(..., description="Chapter name")
+    difficulty: str = Field(..., description="Difficulty level")
+    bloom_level: str = Field(..., description="Bloom taxonomy level")
+
+
+class LORelationship(BaseModel):
+    """A relationship between learning outcomes."""
+    
+    from_lo_id: str = Field(..., description="Source learning outcome ID")
+    to_lo_id: str = Field(..., description="Target learning outcome ID")
+    relationship_type: str = Field(..., description="Type of relationship")
+    strength: float = Field(..., ge=0.0, le=1.0, description="Relationship strength")
+
+
+class KnowledgeGraphResponse(BaseModel):
+    """Response for knowledge graph queries."""
+    
+    model_config = ConfigDict(extra="forbid")
+    
+    lo_id: str = Field(..., description="Queried learning outcome ID")
+    source: str = Field(default="knowledge_graph", description="Data source")
+    timestamp: str = Field(..., description="Response timestamp")
+    
+    # Core LO information
+    lo_info: LONode = Field(..., description="Learning outcome details")
+    
+    # Graph relationships
+    prerequisites: list[LONode] = Field(default_factory=list, description="Prerequisite learning outcomes")
+    successors: list[LONode] = Field(default_factory=list, description="Dependent learning outcomes")
+    
+    # Metadata
+    prerequisite_count: int = Field(..., ge=0, description="Number of prerequisites")
+    successor_count: int = Field(..., ge=0, description="Number of successors")
+    depth_from_root: int = Field(..., ge=0, description="Depth in dependency chain")
+
+
+class KnowledgeGraphRequest(BaseModel):
+    """Request for knowledge graph queries."""
+    
+    model_config = ConfigDict(extra="forbid")
+    
+    lo_id: str = Field(..., description="Learning outcome ID to query")
+    include_prerequisites: bool = Field(default=True, description="Include prerequisite LOs")
+    include_successors: bool = Field(default=True, description="Include successor LOs")
+    max_depth: int = Field(default=2, ge=1, le=5, description="Maximum depth to traverse")

app/schemas/learning_path.py

@@ -0,0 +1,66 @@
+"""Pydantic schemas for adaptive learning path endpoints."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class LearningPathStep(BaseModel):
+    """A single step in a learning path."""
+    
+    step_number: int = Field(..., ge=1, description="Step order in the path")
+    lo_id: str = Field(..., description="Learning outcome ID")
+    title: str = Field(..., description="Learning outcome title")
+    grade: int = Field(..., ge=6, le=8, description="Grade level")
+    subject: str = Field(..., description="Subject name")
+    chapter: str = Field(..., description="Chapter name")
+    difficulty: str = Field(..., description="Difficulty level")
+    bloom_level: str = Field(..., description="Bloom taxonomy level")
+    
+    # Student-specific context
+    current_mastery: float = Field(..., ge=0.0, le=1.0, description="Student's current mastery score")
+    mastery_label: str = Field(..., description="Student's mastery label")
+    is_prerequisite: bool = Field(..., description="Whether this is a prerequisite for the target")
+    estimated_study_time: int = Field(..., ge=0, description="Estimated study time in minutes")
+    
+    # Reasoning
+    reason: str = Field(..., description="Why this step is recommended")
+
+
+class LearningPathRequest(BaseModel):
+    """Request for adaptive learning path generation."""
+    
+    model_config = ConfigDict(extra="forbid")
+    
+    student_id: str = Field(..., description="Student ID")
+    target_lo_id: str = Field(..., description="Target learning outcome ID")
+    max_steps: int = Field(default=10, ge=1, le=20, description="Maximum number of steps in path")
+    include_mastered: bool = Field(default=False, description="Include already mastered LOs for review")
+    difficulty_preference: str = Field(default="adaptive", description="Difficulty preference: easy, medium, hard, adaptive")
+
+
+class LearningPathResponse(BaseModel):
+    """Response for adaptive learning path generation."""
+    
+    model_config = ConfigDict(extra="forbid")
+    
+    student_id: str = Field(..., description="Student ID")
+    target_lo_id: str = Field(..., description="Target learning outcome ID")
+    model_version: str = Field(default="adaptive_path_v2_baseline_001", description="Service version")
+    source: str = Field(default="knowledge_graph_traversal", description="Path generation method")
+    timestamp: str = Field(..., description="Response timestamp")
+    
+    # Path details
+    learning_path: list[LearningPathStep] = Field(..., description="Ordered learning steps")
+    total_steps: int = Field(..., ge=0, description="Total number of steps")
+    estimated_total_time: int = Field(..., ge=0, description="Total estimated study time in minutes")
+    
+    # Student context
+    current_overall_mastery: float = Field(..., ge=0.0, le=1.0, description="Student's overall mastery")
+    weak_prerequisites: list[str] = Field(default_factory=list, description="Weak prerequisite LO IDs")
+    
+    # Path metadata
+    path_difficulty: str = Field(..., description="Overall path difficulty")
+    completion_probability: float = Field(..., ge=0.0, le=1.0, description="Estimated completion probability")
+    
+    # Recommendations
+    next_action: str = Field(..., description="Immediate next action for student")
+    teacher_notes: str = Field(..., description="Notes for teacher intervention")

app/services/adaptive_learning_path_service.py

@@ -0,0 +1,401 @@
+"""Adaptive learning path service.
+
+Generates personalized learning sequences for students based on their
+current mastery profile, target learning outcomes, and knowledge graph
+dependencies. Uses rule-based path optimization with prerequisite analysis.
+"""
+
+import logging
+from datetime import datetime, timezone
+from typing import Dict, List, Tuple
+
+import pandas as pd
+
+from app.core.exceptions import EntityNotFoundError, DatasetError
+from app.data.loader import DatasetLoader
+from app.services.knowledge_graph_service import KnowledgeGraphService
+from app.schemas.learning_path import (
+    LearningPathRequest,
+    LearningPathResponse,
+    LearningPathStep
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AdaptiveLearningPathService:
+    """Generates adaptive learning paths for students.
+    
+    Uses knowledge graph traversal combined with student mastery profiles
+    to create personalized learning sequences. Prioritizes weak prerequisites
+    and respects dependency chains while considering difficulty progression.
+    """
+
+    def __init__(self, loader: DatasetLoader, knowledge_graph: KnowledgeGraphService) -> None:
+        self._loader = loader
+        self._knowledge_graph = knowledge_graph
+        
+        # Difficulty to study time mapping (minutes)
+        self._difficulty_time_map = {
+            "easy": 15,
+            "medium": 25,
+            "hard": 40
+        }
+        
+        # Mastery thresholds
+        self._mastery_thresholds = {
+            "weak": 0.4,
+            "developing": 0.6,
+            "proficient": 0.8
+        }
+
+    def generate_learning_path(self, request: LearningPathRequest) -> LearningPathResponse:
+        """Generate an adaptive learning path for a student.
+        
+        Algorithm:
+        1. Load student's current mastery profile
+        2. Identify prerequisites for target LO that are weak/missing
+        3. Build ordered learning sequence respecting dependencies
+        4. Add difficulty progression and time estimates
+        5. Generate completion probability and recommendations
+        
+        Args:
+            request: Learning path generation request
+            
+        Returns:
+            LearningPathResponse with ordered learning steps
+            
+        Raises:
+            EntityNotFoundError: If student or target LO not found
+        """
+        timestamp = datetime.now(timezone.utc).isoformat()
+        
+        # 1. Validate and load student mastery profile
+        student_mastery = self._load_student_mastery(request.student_id)
+        
+        # 2. Validate target LO exists
+        target_lo_info = self._get_lo_info(request.target_lo_id)
+        
+        # 3. Get all prerequisites for target LO
+        all_prerequisites = self._knowledge_graph.get_prerequisites(
+            request.target_lo_id, 
+            max_depth=None
+        )
+        
+        # 4. Identify weak prerequisites that need attention
+        weak_prerequisites = self._identify_weak_prerequisites(
+            all_prerequisites, 
+            student_mastery,
+            request.include_mastered
+        )
+        
+        # 5. Build learning path with dependency ordering
+        learning_steps = self._build_learning_path(
+            weak_prerequisites,
+            request.target_lo_id,
+            student_mastery,
+            request.max_steps,
+            request.difficulty_preference
+        )
+        
+        # 6. Calculate path metadata
+        total_time = sum(step.estimated_study_time for step in learning_steps)
+        overall_mastery = self._calculate_overall_mastery(student_mastery)
+        path_difficulty = self._determine_path_difficulty(learning_steps)
+        completion_probability = self._estimate_completion_probability(
+            learning_steps, 
+            overall_mastery
+        )
+        
+        # 7. Generate recommendations
+        next_action, teacher_notes = self._generate_recommendations(
+            learning_steps, 
+            weak_prerequisites,
+            overall_mastery
+        )
+        
+        return LearningPathResponse(
+            student_id=request.student_id,
+            target_lo_id=request.target_lo_id,
+            timestamp=timestamp,
+            learning_path=learning_steps,
+            total_steps=len(learning_steps),
+            estimated_total_time=total_time,
+            current_overall_mastery=overall_mastery,
+            weak_prerequisites=weak_prerequisites,
+            path_difficulty=path_difficulty,
+            completion_probability=completion_probability,
+            next_action=next_action,
+            teacher_notes=teacher_notes
+        )
+
+    def _load_student_mastery(self, student_id: str) -> Dict[str, float]:
+        """Load student's mastery profile as a dictionary.
+        
+        Returns:
+            Dict mapping lo_id to mastery_score
+        """
+        try:
+            # Validate student exists
+            student_profiles = self._loader.load_table("student_profiles")
+            if student_id not in student_profiles["student_id"].values:
+                raise EntityNotFoundError(f"Student '{student_id}' not found")
+            
+            # Load mastery profiles
+            mastery_profiles = self._loader.load_table("mastery_profiles")
+            student_mastery = mastery_profiles[
+                mastery_profiles["student_id"] == student_id
+            ]
+            
+            # Convert to dictionary
+            mastery_dict = {}
+            for _, row in student_mastery.iterrows():
+                lo_id = str(row["lo_id"])
+                mastery_score = float(row.get("mastery_score", 0.0))
+                mastery_dict[lo_id] = max(0.0, min(1.0, mastery_score))
+            
+            return mastery_dict
+            
+        except Exception as exc:
+            logger.error("Failed to load student mastery for %s: %s", student_id, exc)
+            raise EntityNotFoundError(f"Unable to load mastery profile for student '{student_id}'") from exc
+
+    def _get_lo_info(self, lo_id: str) -> Dict:
+        """Get learning outcome metadata."""
+        try:
+            learning_outcomes = self._loader.load_table("learning_outcomes")
+            lo_row = learning_outcomes[learning_outcomes["lo_id"] == lo_id]
+            
+            if lo_row.empty:
+                raise EntityNotFoundError(f"Learning outcome '{lo_id}' not found")
+            
+            return lo_row.iloc[0].to_dict()
+            
+        except Exception as exc:
+            logger.error("Failed to get LO info for %s: %s", lo_id, exc)
+            raise EntityNotFoundError(f"Learning outcome '{lo_id}' not found") from exc
+
+    def _identify_weak_prerequisites(
+        self, 
+        prerequisites: List[str], 
+        student_mastery: Dict[str, float],
+        include_mastered: bool
+    ) -> List[str]:
+        """Identify prerequisites that need attention based on mastery scores."""
+        weak_prerequisites = []
+        
+        for lo_id in prerequisites:
+            mastery_score = student_mastery.get(lo_id, 0.0)
+            
+            # Include if weak/developing or if explicitly requested
+            if mastery_score < self._mastery_thresholds["proficient"]:
+                weak_prerequisites.append(lo_id)
+            elif include_mastered and mastery_score >= self._mastery_thresholds["proficient"]:
+                weak_prerequisites.append(lo_id)
+        
+        return weak_prerequisites
+
+    def _build_learning_path(
+        self,
+        weak_prerequisites: List[str],
+        target_lo_id: str,
+        student_mastery: Dict[str, float],
+        max_steps: int,
+        difficulty_preference: str
+    ) -> List[LearningPathStep]:
+        """Build ordered learning path respecting dependencies."""
+        learning_steps = []
+        
+        # Add weak prerequisites in dependency order
+        ordered_prerequisites = self._order_by_dependencies(weak_prerequisites)
+        
+        step_number = 1
+        for lo_id in ordered_prerequisites[:max_steps-1]:  # Reserve one step for target
+            step = self._create_learning_step(
+                step_number,
+                lo_id,
+                student_mastery,
+                is_prerequisite=True,
+                difficulty_preference=difficulty_preference
+            )
+            learning_steps.append(step)
+            step_number += 1
+        
+        # Add target LO as final step if there's room
+        if step_number <= max_steps:
+            target_step = self._create_learning_step(
+                step_number,
+                target_lo_id,
+                student_mastery,
+                is_prerequisite=False,
+                difficulty_preference=difficulty_preference
+            )
+            learning_steps.append(target_step)
+        
+        return learning_steps
+
+    def _order_by_dependencies(self, lo_ids: List[str]) -> List[str]:
+        """Order LOs by dependency chain (prerequisites first)."""
+        ordered = []
+        remaining = set(lo_ids)
+        
+        while remaining:
+            # Find LOs with no remaining prerequisites
+            ready_los = []
+            for lo_id in remaining:
+                prerequisites = self._knowledge_graph.get_prerequisites(lo_id, max_depth=1)
+                if not any(prereq in remaining for prereq in prerequisites):
+                    ready_los.append(lo_id)
+            
+            if not ready_los:
+                # Break cycles by taking the first remaining LO
+                ready_los = [next(iter(remaining))]
+            
+            # Sort by difficulty (easier first) and add to ordered list
+            ready_los.sort(key=lambda lo: self._get_difficulty_score(lo))
+            ordered.extend(ready_los)
+            remaining -= set(ready_los)
+        
+        return ordered
+
+    def _create_learning_step(
+        self,
+        step_number: int,
+        lo_id: str,
+        student_mastery: Dict[str, float],
+        is_prerequisite: bool,
+        difficulty_preference: str
+    ) -> LearningPathStep:
+        """Create a learning path step with metadata."""
+        lo_info = self._get_lo_info(lo_id)
+        mastery_score = student_mastery.get(lo_id, 0.0)
+        mastery_label = self._get_mastery_label(mastery_score)
+        
+        # Estimate study time based on difficulty and current mastery
+        difficulty = str(lo_info.get("difficulty", "medium")).lower()
+        base_time = self._difficulty_time_map.get(difficulty, 25)
+        
+        # Adjust time based on mastery (less time if already partially mastered)
+        time_multiplier = max(0.3, 1.0 - mastery_score)
+        estimated_time = int(base_time * time_multiplier)
+        
+        # Generate reason for inclusion
+        if is_prerequisite:
+            if mastery_score < self._mastery_thresholds["weak"]:
+                reason = f"Weak prerequisite (mastery: {mastery_score:.1%}) - needs foundational work"
+            elif mastery_score < self._mastery_thresholds["developing"]:
+                reason = f"Developing prerequisite (mastery: {mastery_score:.1%}) - needs reinforcement"
+            else:
+                reason = f"Prerequisite review (mastery: {mastery_score:.1%}) - ensure solid foundation"
+        else:
+            reason = f"Target learning outcome - current mastery: {mastery_score:.1%}"
+        
+        return LearningPathStep(
+            step_number=step_number,
+            lo_id=lo_id,
+            title=str(lo_info.get("title", "")),
+            grade=int(lo_info.get("grade", 6)),
+            subject=str(lo_info.get("subject", "")),
+            chapter=str(lo_info.get("chapter", "")),
+            difficulty=difficulty,
+            bloom_level=str(lo_info.get("bloom_level", "Understand")),
+            current_mastery=mastery_score,
+            mastery_label=mastery_label,
+            is_prerequisite=is_prerequisite,
+            estimated_study_time=estimated_time,
+            reason=reason
+        )
+
+    def _get_difficulty_score(self, lo_id: str) -> int:
+        """Get numeric difficulty score for sorting (easier first)."""
+        try:
+            lo_info = self._get_lo_info(lo_id)
+            difficulty = str(lo_info.get("difficulty", "medium")).lower()
+            return {"easy": 1, "medium": 2, "hard": 3}.get(difficulty, 2)
+        except Exception:
+            return 2
+
+    def _get_mastery_label(self, mastery_score: float) -> str:
+        """Convert mastery score to label."""
+        if mastery_score < self._mastery_thresholds["weak"]:
+            return "weak"
+        elif mastery_score < self._mastery_thresholds["developing"]:
+            return "developing"
+        elif mastery_score < self._mastery_thresholds["proficient"]:
+            return "proficient"
+        else:
+            return "mastered"
+
+    def _calculate_overall_mastery(self, student_mastery: Dict[str, float]) -> float:
+        """Calculate student's overall mastery score."""
+        if not student_mastery:
+            return 0.0
+        return sum(student_mastery.values()) / len(student_mastery)
+
+    def _determine_path_difficulty(self, learning_steps: List[LearningPathStep]) -> str:
+        """Determine overall path difficulty."""
+        if not learning_steps:
+            return "easy"
+        
+        difficulty_counts = {"easy": 0, "medium": 0, "hard": 0}
+        for step in learning_steps:
+            difficulty_counts[step.difficulty] += 1
+        
+        # Return the most common difficulty
+        return max(difficulty_counts, key=difficulty_counts.get)
+
+    def _estimate_completion_probability(
+        self, 
+        learning_steps: List[LearningPathStep], 
+        overall_mastery: float
+    ) -> float:
+        """Estimate probability of path completion."""
+        if not learning_steps:
+            return 1.0
+        
+        # Base probability from overall mastery
+        base_prob = 0.3 + (overall_mastery * 0.5)
+        
+        # Adjust for path length (longer paths are harder to complete)
+        length_penalty = max(0.1, 1.0 - (len(learning_steps) * 0.05))
+        
+        # Adjust for difficulty distribution
+        hard_steps = sum(1 for step in learning_steps if step.difficulty == "hard")
+        difficulty_penalty = max(0.1, 1.0 - (hard_steps * 0.1))
+        
+        completion_prob = base_prob * length_penalty * difficulty_penalty
+        return max(0.1, min(0.95, completion_prob))
+
+    def _generate_recommendations(
+        self,
+        learning_steps: List[LearningPathStep],
+        weak_prerequisites: List[str],
+        overall_mastery: float
+    ) -> Tuple[str, str]:
+        """Generate next action and teacher notes."""
+        if not learning_steps:
+            next_action = "No learning path needed - target already mastered"
+            teacher_notes = "Student has strong mastery of target and prerequisites"
+            return next_action, teacher_notes
+        
+        first_step = learning_steps[0]
+        
+        # Next action
+        if first_step.current_mastery < self._mastery_thresholds["weak"]:
+            next_action = f"Start with foundational work on {first_step.title}"
+        else:
+            next_action = f"Begin with {first_step.title} ({first_step.estimated_study_time} min)"
+        
+        # Teacher notes
+        weak_count = len(weak_prerequisites)
+        if weak_count == 0:
+            teacher_notes = "Student is ready for target LO with minimal prerequisite work"
+        elif weak_count <= 3:
+            teacher_notes = f"Student needs work on {weak_count} prerequisites before target LO"
+        else:
+            teacher_notes = f"Student has {weak_count} weak prerequisites - consider breaking into smaller goals"
+        
+        if overall_mastery < 0.4:
+            teacher_notes += ". Consider additional support or scaffolding."
+        
+        return next_action, teacher_notes

app/services/knowledge_graph_service.py

@@ -0,0 +1,318 @@
+"""Knowledge graph service for learning outcome dependencies.
+
+Builds and maintains a directed acyclic graph (DAG) of learning outcome
+dependencies from lo_dependencies.csv. Provides graph traversal methods
+for prerequisite chains, successor paths, and dependency analysis.
+"""
+
+import logging
+from datetime import datetime, timezone
+from typing import Dict, List
+
+import networkx as nx
+import pandas as pd
+
+from app.core.exceptions import EntityNotFoundError, DatasetError
+from app.data.loader import DatasetLoader
+from app.schemas.knowledge_graph import (
+    KnowledgeGraphResponse,
+    LONode,
+    LORelationship
+)
+
+logger = logging.getLogger(__name__)
+
+
+class KnowledgeGraphService:
+    """Manages learning outcome dependency graph and provides traversal methods.
+    
+    Loads lo_dependencies.csv and learning_outcomes.csv to build a NetworkX
+    directed graph. Provides methods for finding prerequisites, successors,
+    learning paths, and dependency analysis.
+    """
+
+    def __init__(self, loader: DatasetLoader) -> None:
+        self._loader = loader
+        self._graph: nx.DiGraph | None = None
+        self._lo_metadata: Dict[str, Dict] = {}
+        self._build_graph()
+
+    def _build_graph(self) -> None:
+        """Build the knowledge graph from dataset tables."""
+        try:
+            # Load learning outcomes for metadata
+            learning_outcomes = self._loader.load_table("learning_outcomes")
+            self._lo_metadata = {
+                row["lo_id"]: {
+                    "title": str(row.get("title", "")),
+                    "grade": int(row.get("grade", 6)),
+                    "subject": str(row.get("subject", "")),
+                    "chapter": str(row.get("chapter", "")),
+                    "difficulty": str(row.get("difficulty", "Medium")).lower(),
+                    "bloom_level": str(row.get("bloom_level", "Understand"))
+                }
+                for _, row in learning_outcomes.iterrows()
+            }
+            
+            # Load dependencies and build graph
+            dependencies = self._loader.load_table("lo_dependencies")
+            self._graph = nx.DiGraph()
+            
+            # Add all LO nodes first
+            for lo_id in self._lo_metadata.keys():
+                self._graph.add_node(lo_id)
+            
+            # Strength column is a string category in this dataset — map to float
+            _strength_map = {"weak": 0.33, "medium": 0.66, "strong": 1.0}
+            
+            # Add dependency edges (prerequisite -> dependent)
+            for _, row in dependencies.iterrows():
+                prerequisite_lo = str(row["prerequisite_lo_id"])
+                dependent_lo = str(row["lo_id"])
+                relationship_type = str(row.get("relationship_type", "prerequisite"))
+                raw_strength = row.get("strength", "medium")
+                # Handle both numeric and string strength values
+                try:
+                    strength = float(raw_strength)
+                except (ValueError, TypeError):
+                    strength = _strength_map.get(str(raw_strength).lower(), 0.66)
+                
+                if prerequisite_lo in self._lo_metadata and dependent_lo in self._lo_metadata:
+                    self._graph.add_edge(
+                        prerequisite_lo,
+                        dependent_lo,
+                        relationship_type=relationship_type,
+                        strength=strength
+                    )
+            
+            logger.info(
+                "Built knowledge graph: %d nodes, %d edges",
+                self._graph.number_of_nodes(),
+                self._graph.number_of_edges()
+            )
+            
+        except Exception as exc:
+            logger.error("Failed to build knowledge graph: %s", exc)
+            raise DatasetError(f"Knowledge graph construction failed: {exc}") from exc
+
+    def get_knowledge_graph(self, lo_id: str, max_depth: int = 2) -> KnowledgeGraphResponse:
+        """Get knowledge graph information for a learning outcome.
+        
+        Args:
+            lo_id: Learning outcome ID to query
+            max_depth: Maximum depth to traverse for prerequisites/successors
+            
+        Returns:
+            KnowledgeGraphResponse with LO info and relationships
+            
+        Raises:
+            EntityNotFoundError: If lo_id is not found in the graph
+        """
+        if not self._graph or lo_id not in self._graph:
+            raise EntityNotFoundError(f"Learning outcome '{lo_id}' not found in knowledge graph")
+        
+        timestamp = datetime.now(timezone.utc).isoformat()
+        
+        # Get LO metadata
+        lo_info = self._create_lo_node(lo_id)
+        
+        # Get prerequisites (nodes that point to this LO)
+        prerequisites = self._get_prerequisites(lo_id, max_depth)
+        
+        # Get successors (nodes this LO points to)
+        successors = self._get_successors(lo_id, max_depth)
+        
+        # Calculate depth from root (nodes with no predecessors)
+        depth_from_root = self._calculate_depth_from_root(lo_id)
+        
+        return KnowledgeGraphResponse(
+            lo_id=lo_id,
+            timestamp=timestamp,
+            lo_info=lo_info,
+            prerequisites=prerequisites,
+            successors=successors,
+            prerequisite_count=len(prerequisites),
+            successor_count=len(successors),
+            depth_from_root=depth_from_root
+        )
+
+    def get_prerequisites(self, lo_id: str, max_depth: int = None) -> List[str]:
+        """Get all prerequisite LO IDs for a given learning outcome.
+        
+        Args:
+            lo_id: Learning outcome ID
+            max_depth: Maximum depth to traverse (None for all)
+            
+        Returns:
+            List of prerequisite LO IDs in dependency order
+        """
+        if not self._graph or lo_id not in self._graph:
+            return []
+        
+        prerequisites = []
+        visited = set()
+        
+        def _traverse_prerequisites(current_lo: str, depth: int) -> None:
+            if max_depth is not None and depth >= max_depth:
+                return
+            if current_lo in visited:
+                return
+            
+            visited.add(current_lo)
+            
+            # Get direct prerequisites
+            for pred in self._graph.predecessors(current_lo):
+                if pred not in prerequisites:
+                    prerequisites.append(pred)
+                _traverse_prerequisites(pred, depth + 1)
+        
+        _traverse_prerequisites(lo_id, 0)
+        return prerequisites
+
+    def get_successors(self, lo_id: str, max_depth: int = None) -> List[str]:
+        """Get all successor LO IDs for a given learning outcome.
+        
+        Args:
+            lo_id: Learning outcome ID
+            max_depth: Maximum depth to traverse (None for all)
+            
+        Returns:
+            List of successor LO IDs
+        """
+        if not self._graph or lo_id not in self._graph:
+            return []
+        
+        successors = []
+        visited = set()
+        
+        def _traverse_successors(current_lo: str, depth: int) -> None:
+            if max_depth is not None and depth >= max_depth:
+                return
+            if current_lo in visited:
+                return
+            
+            visited.add(current_lo)
+            
+            # Get direct successors
+            for succ in self._graph.successors(current_lo):
+                if succ not in successors:
+                    successors.append(succ)
+                _traverse_successors(succ, depth + 1)
+        
+        _traverse_successors(lo_id, 0)
+        return successors
+
+    def get_learning_path(self, start_lo: str, target_lo: str) -> List[str]:
+        """Find the shortest learning path between two learning outcomes.
+        
+        Args:
+            start_lo: Starting learning outcome ID
+            target_lo: Target learning outcome ID
+            
+        Returns:
+            List of LO IDs representing the shortest path
+            
+        Raises:
+            EntityNotFoundError: If either LO is not found or no path exists
+        """
+        if not self._graph:
+            raise DatasetError("Knowledge graph not initialized")
+        
+        if start_lo not in self._graph:
+            raise EntityNotFoundError(f"Start LO '{start_lo}' not found in knowledge graph")
+        
+        if target_lo not in self._graph:
+            raise EntityNotFoundError(f"Target LO '{target_lo}' not found in knowledge graph")
+        
+        try:
+            # Find shortest path in the directed graph
+            path = nx.shortest_path(self._graph, start_lo, target_lo)
+            return path
+        except nx.NetworkXNoPath:
+            # No direct path - check if target is a prerequisite of start
+            try:
+                reverse_path = nx.shortest_path(self._graph, target_lo, start_lo)
+                # Return reverse path (target should be learned first)
+                return list(reversed(reverse_path))
+            except nx.NetworkXNoPath:
+                raise EntityNotFoundError(
+                    f"No learning path found between '{start_lo}' and '{target_lo}'"
+                )
+
+    def is_prerequisite(self, prerequisite_lo: str, dependent_lo: str) -> bool:
+        """Check if one LO is a prerequisite of another.
+        
+        Args:
+            prerequisite_lo: Potential prerequisite LO ID
+            dependent_lo: Dependent LO ID
+            
+        Returns:
+            True if prerequisite_lo is a prerequisite of dependent_lo
+        """
+        if not self._graph:
+            return False
+        
+        return nx.has_path(self._graph, prerequisite_lo, dependent_lo)
+
+    def get_root_los(self) -> List[str]:
+        """Get all root learning outcomes (no prerequisites).
+        
+        Returns:
+            List of LO IDs that have no prerequisites
+        """
+        if not self._graph:
+            return []
+        
+        return [node for node in self._graph.nodes() if self._graph.in_degree(node) == 0]
+
+    def get_leaf_los(self) -> List[str]:
+        """Get all leaf learning outcomes (no successors).
+        
+        Returns:
+            List of LO IDs that have no successors
+        """
+        if not self._graph:
+            return []
+        
+        return [node for node in self._graph.nodes() if self._graph.out_degree(node) == 0]
+
+    def _get_prerequisites(self, lo_id: str, max_depth: int) -> List[LONode]:
+        """Get prerequisite LO nodes with metadata."""
+        prerequisite_ids = self.get_prerequisites(lo_id, max_depth)
+        return [self._create_lo_node(lo_id) for lo_id in prerequisite_ids]
+
+    def _get_successors(self, lo_id: str, max_depth: int) -> List[LONode]:
+        """Get successor LO nodes with metadata."""
+        successor_ids = self.get_successors(lo_id, max_depth)
+        return [self._create_lo_node(lo_id) for lo_id in successor_ids]
+
+    def _create_lo_node(self, lo_id: str) -> LONode:
+        """Create an LONode from LO metadata."""
+        metadata = self._lo_metadata.get(lo_id, {})
+        return LONode(
+            lo_id=lo_id,
+            title=metadata.get("title", ""),
+            grade=metadata.get("grade", 6),
+            subject=metadata.get("subject", ""),
+            chapter=metadata.get("chapter", ""),
+            difficulty=metadata.get("difficulty", "medium"),
+            bloom_level=metadata.get("bloom_level", "Understand")
+        )
+
+    def _calculate_depth_from_root(self, lo_id: str) -> int:
+        """Calculate the depth of an LO from root nodes."""
+        if not self._graph:
+            return 0
+        
+        # Find shortest path from any root to this LO
+        root_los = self.get_root_los()
+        min_depth = float('inf')
+        
+        for root_lo in root_los:
+            try:
+                path = nx.shortest_path(self._graph, root_lo, lo_id)
+                min_depth = min(min_depth, len(path) - 1)
+            except nx.NetworkXNoPath:
+                continue
+        
+        return int(min_depth) if min_depth != float('inf') else 0

requirements.txt

@@ -15,6 +15,9 @@ pandas==2.2.3
 scikit-learn==1.6.1
 joblib==1.4.2
 
+# --- Graph Processing ---
+networkx==3.4.2
+
 # --- Environment ---
 python-dotenv==1.0.1
 huggingface-hub==0.17.0