Upload 40 files

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+uploads/20260307_154626_42dcb39b_resume.pdf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.env
+venv/
+uploads/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+alembic/versions/

Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+RUN mkdir -p uploads
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,119 @@
----
-title: Healthtech Api
-emoji: ⚡
-colorFrom: yellow
-colorTo: indigo
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: LearnHub AI Platform
+emoji: 🎓
+colorFrom: purple
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# LearnHub - Phase 2 AI Learning Platform
+
+**Advanced AI-powered learning platform with multi-user support, course management, and RAG-based tutoring.**
+
+## Features
+
+✅ **User Authentication** - JWT-based auth with student/instructor/admin roles  
+✅ **Course Management** - Modules, lessons, quizzes, and progress tracking  
+✅ **AI Tutor** - RAG-powered Q&A using PostgreSQL pgvector + Google Gemini  
+✅ **Smart Features** - Auto-generate summaries, MCQs, and progressive hints  
+✅ **Forum** - Discussion boards for students and instructors  
+✅ **Vector Search** - pgvector for semantic search over course materials
+
+## Tech Stack
+
+- **Backend**: FastAPI + SQLAlchemy + PostgreSQL  
+- **Vector DB**: pgvector extension for PostgreSQL  
+- **AI**: Google Gemini 2.5 Flash + LangChain  
+- **Auth**: JWT tokens with bcrypt password hashing  
+
+## Deployment on HuggingFace Spaces
+
+This Space requires a **PostgreSQL database with pgvector extension**.
+
+### Option 1: Use Supabase (Recommended)
+
+1. Create a Supabase project at https://supabase.com
+2. Go to Project Settings → Database → Connection string (URI)
+3. Enable pgvector: Go to SQL Editor and run:
+   ```sql
+   CREATE EXTENSION vector;
+   ```
+4. Add your Supabase connection string as `DATABASE_URL` secret in HF Spaces
+
+### Option 2: Use Render PostgreSQL
+
+1. Create a PostgreSQL database on Render.com
+2. Connect and enable pgvector:
+   ```sql
+   CREATE EXTENSION vector;
+   ```
+3. Use the external connection string as `DATABASE_URL`
+
+### Required Secrets
+
+Configure in **Settings → Variables and secrets**:
+
+```
+DATABASE_URL=postgresql+asyncpg://user:password@host:5432/database
+GOOGLE_API_KEY=your_google_api_key
+JWT_SECRET_KEY=your-super-secret-jwt-key
+CORS_ORIGINS=https://your-frontend.vercel.app
+```
+
+### Run Database Migrations
+
+After deployment, you need to run Alembic migrations:
+
+```bash
+# Connect to your database and enable pgvector
+CREATE EXTENSION IF NOT EXISTS vector;
+
+# Or use the migration script in alembic/versions/
+```
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /auth/register` | Register new user |
+| `POST /auth/login` | Login and get JWT token |
+| `GET /courses` | List all courses |
+| `POST /tutor/ask` | Ask AI tutor a question (RAG) |
+| `POST /tutor/generate-mcq` | Generate MCQ questions |
+| `POST /tutor/hint` | Get progressive hints |
+| `GET /docs` | Interactive API documentation |
+
+## Local Development
+
+```bash
+# Setup
+cd backend
+pip install -r requirements.txt
+
+# Configure .env
+cp .env.example .env
+# Edit .env with your credentials
+
+# Run migrations
+alembic upgrade head
+
+# Start server
+uvicorn app.main:app --reload --port 8001
+```
+
+## Differences from Phase 1
+
+| Feature | Phase 1 | Phase 2 |
+|---------|---------|---------|
+| Database | SQLite | PostgreSQL |
+| Vectors | Pinecone | pgvector (PostgreSQL) |
+| Auth | None | JWT multi-user |
+| Courses | No | Full course management |
+| AI Features | Basic Q&A | Q&A + MCQ + Summaries + Hints |
+| Users | Single | Multi-user with roles |
+
+---
+
+**Note**: This is the backend API only. For a full app experience, deploy the Next.js frontend separately and connect via CORS.

alembic.ini

@@ -0,0 +1,40 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+sqlalchemy.url = sqlite:///./placeholder.db
+
+[post_write_hooks]
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration.

alembic/env.py

@@ -0,0 +1,97 @@
+from logging.config import fileConfig
+import asyncio
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+
+# Import all models here
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from app.database import Base
+from app.config import settings
+from app.models.user import User
+from app.models.course import Course, Module, Lesson
+from app.models.progress import Enrollment, Progress, StudyStreak
+from app.models.quiz import Quiz, QuizQuestion, QuizAttempt
+from app.models.forum import ForumPost, ForumComment
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Override sqlalchemy.url with our settings
+config.set_main_option("sqlalchemy.url", settings.DATABASE_URL)
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+target_metadata = Base.metadata
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """Run migrations in 'online' mode with async support."""
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

alembic/versions/add_pgvector_001.py

@@ -0,0 +1,58 @@
+"""Enable pgvector extension and create documents table
+
+Revision ID: add_pgvector_001
+Revises: 
+Create Date: 2026-03-07 01:00:00.000000
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = 'add_pgvector_001'
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Enable pgvector extension
+    op.execute('CREATE EXTENSION IF NOT EXISTS vector')
+    
+    # Create documents table with vector column
+    op.create_table(
+        'documents',
+        sa.Column('id', sa.String(36), primary_key=True),
+        sa.Column('content', sa.Text(), nullable=False),
+        sa.Column('embedding', postgresql.ARRAY(sa.Float), nullable=False),
+        sa.Column('meta', sa.JSON(), nullable=True),
+        sa.Column('filename', sa.String(500), nullable=True),
+        sa.Column('file_path', sa.String(1000), nullable=True),
+        sa.Column('chunk_index', sa.Integer(), default=0),
+        sa.Column('created_at', sa.DateTime(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(), nullable=False),
+    )
+    
+    # Create index for vector similarity search
+    op.execute('''
+        CREATE INDEX documents_embedding_idx 
+        ON documents 
+        USING ivfflat (embedding vector_cosine_ops)
+        WITH (lists = 100)
+    ''')
+    
+    # Create index on meta for filtering
+    op.create_index(
+        'ix_documents_meta',
+        'documents',
+        ['meta'],
+        postgresql_using='gin'
+    )
+
+
+def downgrade() -> None:
+    op.drop_index('ix_documents_meta', table_name='documents')
+    op.execute('DROP INDEX IF EXISTS documents_embedding_idx')
+    op.drop_table('documents')
+    op.execute('DROP EXTENSION IF EXISTS vector')

app/config.py

@@ -0,0 +1,48 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from typing import List
+import os
+from pathlib import Path
+
+# Get the backend directory path
+BACKEND_DIR = Path(__file__).resolve().parent.parent
+ENV_FILE = BACKEND_DIR / ".env"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=str(ENV_FILE),
+        env_file_encoding="utf-8",
+        case_sensitive=False
+    )
+
+    # Database
+    DATABASE_URL: str = "postgresql+asyncpg://learnhub:learnhub_secret@localhost:5432/learnhub"
+
+    # Google Gemini
+    GOOGLE_API_KEY: str = ""
+
+    # JWT Auth
+    JWT_SECRET_KEY: str = "change-this-secret-key"
+    JWT_ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+    REFRESH_TOKEN_EXPIRE_DAYS: int = 7
+
+    # App settings
+    APP_ENV: str = "development"
+    CORS_ORIGINS: str = "http://localhost:3001"
+    UPLOAD_DIR: str = "./uploads"
+    MAX_UPLOAD_SIZE_MB: int = 50
+
+    # AI Settings
+    EMBEDDING_MODEL: str = "sentence-transformers/all-MiniLM-L6-v2"
+    LLM_MODEL: str = "gemini-2.5-flash"
+
+    @property
+    def cors_origins_list(self) -> List[str]:
+        return [origin.strip() for origin in self.CORS_ORIGINS.split(",")]
+
+
+settings = Settings()
+
+# Ensure upload directory exists
+os.makedirs(settings.UPLOAD_DIR, exist_ok=True)

app/database.py

@@ -0,0 +1,39 @@
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.pool import AsyncAdaptedQueuePool
+from app.config import settings
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+# Use connection pooling for faster responses
+# Direct connection with AsyncAdaptedQueuePool keeps connections open and reuses them
+engine = create_async_engine(
+    settings.DATABASE_URL.replace("+asyncpg://", "+psycopg://"),
+    echo=False,
+    future=True,
+    poolclass=AsyncAdaptedQueuePool,
+    pool_size=5,           # Keep 5 connections ready
+    max_overflow=10,       # Allow up to 15 total (5 + 10)
+    pool_timeout=30,       # Wait up to 30s for a connection
+    pool_recycle=1800,     # Recycle connections every 30 minutes
+    pool_pre_ping=True,    # Verify connections are alive before using
+)
+
+async_session_maker = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+async def get_db():
+    async with async_session_maker() as session:
+        yield session
+
+
+async def create_tables():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)

app/dependencies.py

@@ -0,0 +1,128 @@
+"""API dependencies for authentication and database."""
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from types import SimpleNamespace
+from app.database import get_db
+from app.services.auth import decode_token
+from app.models.user import User, UserRole
+from datetime import datetime
+
+
+security = HTTPBearer()
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+    db: AsyncSession = Depends(get_db),
+) -> User:
+    """Get current authenticated user from JWT token."""
+    token = credentials.credentials
+    payload = decode_token(token)
+
+    if not payload:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    if payload.get("type") != "access":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token type",
+        )
+
+    user_id = payload.get("sub")
+    email = payload.get("email", "demo@example.com")
+    role = payload.get("role", "student")
+    
+    # Check if this is a demo user (IDs contain "demo")
+    if user_id and "demo" in str(user_id):
+        # Return a plain object (no ORM) to avoid SQLAlchemy mapper issues
+        full_name_map = {
+            "admin-demo-001": "Admin Demo",
+            "instructor-demo-001": "Instructor Demo",
+            "student-demo-001": "Student Demo",
+        }
+        return SimpleNamespace(
+            id=user_id,
+            email=email,
+            hashed_password="",
+            full_name=full_name_map.get(user_id, "Demo User"),
+            role=UserRole(role) if role else UserRole.STUDENT,
+            is_active=True,
+            is_verified=True,
+            bio=None,
+            avatar_url=None,
+            created_at=datetime.utcnow(),
+            updated_at=None,
+            last_login=None,
+        )
+    
+    # Try to fetch from database
+    try:
+        result = await db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+
+        if not user:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="User not found",
+            )
+
+        if not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="User account is deactivated",
+            )
+
+        return user
+    except HTTPException:
+        raise
+    except Exception as e:
+        # Database connection failed, return demo user
+        print(f"⚠️  Could not fetch user from database: {e}, using demo mode")
+        return SimpleNamespace(
+            id=user_id,
+            email=email,
+            hashed_password="",
+            full_name="Demo User",
+            role=UserRole(role) if role else UserRole.STUDENT,
+            is_active=True,
+            is_verified=True,
+            bio=None,
+            avatar_url=None,
+            created_at=datetime.utcnow(),
+            updated_at=None,
+            last_login=None,
+        )
+
+
+async def get_current_active_user(
+    current_user: User = Depends(get_current_user),
+) -> User:
+    """Get current active user."""
+    return current_user
+
+
+def require_role(*roles: UserRole):
+    """Dependency factory for role-based access control."""
+    async def role_checker(
+        current_user: User = Depends(get_current_user),
+    ) -> User:
+        if current_user.role not in roles:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Requires one of these roles: {', '.join(r.value for r in roles)}",
+            )
+        return current_user
+    return role_checker
+
+
+# Convenience dependencies
+require_admin = require_role(UserRole.ADMIN)
+require_instructor = require_role(UserRole.INSTRUCTOR, UserRole.ADMIN)
+require_student = require_role(UserRole.STUDENT, UserRole.INSTRUCTOR, UserRole.ADMIN)

app/main.py

@@ -0,0 +1,108 @@
+"""Phase 2 - Student Learning Platform API."""
+
+import sys
+import asyncio
+
+# Fix for Windows + psycopg async
+if sys.platform == 'win32':
+    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from app.config import settings
+from app.database import create_tables
+from app.routes import auth, courses, progress, tutor, admin, quiz, forum, documents
+
+# Import all models so SQLAlchemy mapper can resolve all relationships
+import app.models.user  # noqa: F401
+import app.models.course  # noqa: F401
+import app.models.progress  # noqa: F401
+import app.models.quiz  # noqa: F401
+import app.models.forum  # noqa: F401
+import app.models.document  # noqa: F401
+
+
+app = FastAPI(
+    title="Student Learning Platform API",
+    description="AI-powered learning platform with courses, progress tracking, and AI tutor",
+    version="2.0.0",
+)
+
+# Register CORS middleware FIRST - it should be the outermost middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"] if settings.APP_ENV == "development" else settings.cors_origins_list,
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"],
+    allow_headers=["*"],
+    max_age=3600,
+)
+
+# Register routes
+app.include_router(auth.router, prefix="/api")
+app.include_router(courses.router, prefix="/api")
+app.include_router(progress.router, prefix="/api")
+app.include_router(tutor.router, prefix="/api")
+app.include_router(admin.router, prefix="/api")
+app.include_router(quiz.router, prefix="/api")
+app.include_router(forum.router, prefix="/api")
+app.include_router(documents.router, prefix="/api")
+
+
+@app.get("/")
+async def root():
+    """Root endpoint."""
+    return {
+        "message": "LearnHub Student Learning Platform API",
+        "version": "2.0.0",
+        "environment": settings.APP_ENV,
+        "docs": "/docs",
+        "health": "/health",
+    }
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint."""
+    db_status = "unknown"
+    try:
+        from app.database import engine
+        async with engine.connect() as conn:
+            await conn.execute("SELECT 1")
+        db_status = "connected"
+    except Exception:
+        db_status = "disconnected"
+    
+    return {
+        "status": "healthy",
+        "version": "2.0.0",
+        "environment": settings.APP_ENV,
+        "database": db_status,
+    }
+
+
+@app.on_event("startup")
+async def startup_event():
+    """Initialize services on startup."""
+    # In development, create tables automatically
+    if settings.APP_ENV == "development":
+        try:
+            await create_tables()
+            print("✅ Database tables created (development mode)")
+        except Exception as e:
+            print(f"⚠️  Database connection failed: {e}")
+            print("⚠️  App will start without database. Some features may not work.")
+
+    # Initialize AI tutor
+    try:
+        from app.services.tutor import tutor_service
+        await tutor_service.initialize()
+        print("✅ AI Tutor service initialized")
+    except Exception as e:
+        print(f"⚠️  AI Tutor initialization failed: {e}")
+        print("⚠️  AI Tutor features may not work properly.")
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("app.main:app", host="0.0.0.0", port=8001, reload=True)

app/models/__init__.py

@@ -0,0 +1,34 @@
+"""Models package."""
+
+from app.models.user import User, UserRole
+from app.models.course import (
+    Course,
+    Module,
+    Lesson,
+    ContentType,
+    DifficultyLevel,
+)
+from app.models.progress import Progress, Enrollment, StudyStreak
+from app.models.quiz import Quiz, QuizQuestion, QuizAttempt, QuestionType
+from app.models.forum import ForumPost, ForumComment
+from app.models.document import Document
+
+__all__ = [
+    "User",
+    "UserRole",
+    "Course",
+    "Module",
+    "Lesson",
+    "ContentType",
+    "DifficultyLevel",
+    "Enrollment",
+    "Progress",
+    "StudyStreak",
+    "Quiz",
+    "QuizQuestion",
+    "QuizAttempt",
+    "QuestionType",
+    "ForumPost",
+    "ForumComment",
+    "Document",
+]

app/models/course.py

@@ -0,0 +1,107 @@
+"""Course and Module models for content organization."""
+
+from datetime import datetime
+from enum import Enum as PyEnum
+from sqlalchemy import Column, String, Boolean, DateTime, Enum, Text, Integer, ForeignKey
+from sqlalchemy.orm import relationship
+from uuid import uuid4
+from app.database import Base
+
+
+class ContentType(str, PyEnum):
+    PDF = "pdf"
+    VIDEO = "video"
+    MARKDOWN = "markdown"
+    QUIZ = "quiz"
+    EXTERNAL_LINK = "external_link"
+
+
+class DifficultyLevel(str, PyEnum):
+    BEGINNER = "beginner"
+    INTERMEDIATE = "intermediate"
+    ADVANCED = "advanced"
+
+
+class Course(Base):
+    __tablename__ = "courses"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    title = Column(String(255), nullable=False)
+    slug = Column(String(255), unique=True, nullable=False, index=True)
+    description = Column(Text, nullable=True)
+    thumbnail_url = Column(String(500), nullable=True)
+    difficulty = Column(Enum(DifficultyLevel), default=DifficultyLevel.BEGINNER)
+    is_published = Column(Boolean, default=False)
+    is_featured = Column(Boolean, default=False)
+    estimated_hours = Column(Integer, default=0)
+    order_index = Column(Integer, default=0)
+
+    # Creator
+    created_by = Column(String(36), ForeignKey("users.id"), nullable=True)
+
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    # Relationships
+    modules = relationship("Module", back_populates="course", cascade="all, delete-orphan", order_by="Module.order_index")
+    enrollments = relationship("Enrollment", back_populates="course", cascade="all, delete-orphan")
+
+    def __repr__(self):
+        return f"<Course {self.title}>"
+
+
+class Module(Base):
+    __tablename__ = "modules"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    course_id = Column(String(36), ForeignKey("courses.id"), nullable=False)
+    title = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    order_index = Column(Integer, default=0)
+    is_published = Column(Boolean, default=False)
+
+    # Unlock requirements
+    prerequisite_module_id = Column(String(36), ForeignKey("modules.id"), nullable=True)
+
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    # Relationships
+    course = relationship("Course", back_populates="modules")
+    lessons = relationship("Lesson", back_populates="module", cascade="all, delete-orphan", order_by="Lesson.order_index")
+    prerequisite = relationship("Module", remote_side="Module.id")
+
+    def __repr__(self):
+        return f"<Module {self.title}>"
+
+
+class Lesson(Base):
+    __tablename__ = "lessons"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    module_id = Column(String(36), ForeignKey("modules.id"), nullable=False)
+    title = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    content_type = Column(Enum(ContentType), nullable=False)
+    content_url = Column(String(500), nullable=True)  # File URL or external link
+    content_text = Column(Text, nullable=True)  # For markdown content
+    duration_minutes = Column(Integer, default=0)
+    order_index = Column(Integer, default=0)
+    is_published = Column(Boolean, default=False)
+
+    # Vector store reference
+    vector_namespace = Column(String(255), nullable=True)
+
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    # Relationships
+    module = relationship("Module", back_populates="lessons")
+    progress_records = relationship("Progress", back_populates="lesson", cascade="all, delete-orphan")
+    quizzes = relationship("Quiz", back_populates="lesson", cascade="all, delete-orphan")
+
+    def __repr__(self):
+        return f"<Lesson {self.title}>"

app/models/document.py

@@ -0,0 +1,29 @@
+"""Document model for pgvector-based knowledge base."""
+
+from datetime import datetime
+from sqlalchemy import Column, String, Text, DateTime, Integer, JSON
+from pgvector.sqlalchemy import Vector
+from uuid import uuid4
+from app.database import Base
+
+
+class Document(Base):
+    """Vector store for course materials and knowledge base."""
+    __tablename__ = "documents"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    content = Column(Text, nullable=False)
+    embedding = Column(Vector(768), nullable=False)  # Google text-embedding-004 dimension
+    meta = Column(JSON, nullable=True)  # Store lesson_id, module_id, source, etc.
+    
+    # File metadata
+    filename = Column(String(500), nullable=True)
+    file_path = Column(String(1000), nullable=True)
+    chunk_index = Column(Integer, default=0)
+    
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    def __repr__(self):
+        return f"<Document {self.id[:8]}... from {self.filename}>"

app/models/forum.py

@@ -0,0 +1,56 @@
+"""Forum and discussion models for peer interaction."""
+
+from datetime import datetime
+from sqlalchemy import Column, String, Boolean, DateTime, Text, Integer, ForeignKey
+from sqlalchemy.orm import relationship
+from uuid import uuid4
+from app.database import Base
+
+
+class ForumPost(Base):
+    __tablename__ = "forum_posts"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    module_id = Column(String(36), ForeignKey("modules.id"), nullable=True)  # Optional: tie to module
+    author_id = Column(String(36), ForeignKey("users.id"), nullable=False)
+    title = Column(String(255), nullable=False)
+    content = Column(Text, nullable=False)
+    is_pinned = Column(Boolean, default=False)
+    is_resolved = Column(Boolean, default=False)  # For Q&A threads
+    upvotes = Column(Integer, default=0)
+    view_count = Column(Integer, default=0)
+
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    # Relationships
+    author = relationship("User", back_populates="forum_posts")
+    comments = relationship("ForumComment", back_populates="post", cascade="all, delete-orphan")
+
+    def __repr__(self):
+        return f"<ForumPost {self.title}>"
+
+
+class ForumComment(Base):
+    __tablename__ = "forum_comments"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    post_id = Column(String(36), ForeignKey("forum_posts.id"), nullable=False)
+    author_id = Column(String(36), ForeignKey("users.id"), nullable=False)
+    parent_id = Column(String(36), ForeignKey("forum_comments.id"), nullable=True)  # For nested replies
+    content = Column(Text, nullable=False)
+    is_accepted_answer = Column(Boolean, default=False)
+    upvotes = Column(Integer, default=0)
+
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    # Relationships
+    post = relationship("ForumPost", back_populates="comments")
+    author = relationship("User", back_populates="forum_comments")
+    replies = relationship("ForumComment", backref="parent", remote_side="ForumComment.id")
+
+    def __repr__(self):
+        return f"<ForumComment {self.id}>"

app/models/progress.py

@@ -0,0 +1,73 @@
+"""Progress tracking models."""
+
+from datetime import datetime
+from sqlalchemy import Column, String, Boolean, DateTime, Integer, ForeignKey, Float, UniqueConstraint
+from sqlalchemy.orm import relationship
+from uuid import uuid4
+from app.database import Base
+
+
+class Enrollment(Base):
+    __tablename__ = "enrollments"
+    __table_args__ = (
+        UniqueConstraint('student_id', 'course_id', name='unique_enrollment'),
+    )
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    student_id = Column(String(36), ForeignKey("users.id"), nullable=False)
+    course_id = Column(String(36), ForeignKey("courses.id"), nullable=False)
+    enrolled_at = Column(DateTime, default=datetime.utcnow)
+    completed_at = Column(DateTime, nullable=True)
+    is_completed = Column(Boolean, default=False)
+    progress_percentage = Column(Float, default=0.0)
+
+    # Relationships
+    student = relationship("User", back_populates="enrollments")
+    course = relationship("Course", back_populates="enrollments")
+
+    def __repr__(self):
+        return f"<Enrollment {self.student_id} -> {self.course_id}>"
+
+
+class Progress(Base):
+    __tablename__ = "progress"
+    __table_args__ = (
+        UniqueConstraint('student_id', 'lesson_id', name='unique_progress'),
+    )
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    student_id = Column(String(36), ForeignKey("users.id"), nullable=False)
+    lesson_id = Column(String(36), ForeignKey("lessons.id"), nullable=False)
+
+    is_completed = Column(Boolean, default=False)
+    completed_at = Column(DateTime, nullable=True)
+    time_spent_seconds = Column(Integer, default=0)
+    last_position = Column(Integer, default=0)  # For video progress
+
+    # Timestamps
+    started_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    # Relationships
+    student = relationship("User", back_populates="progress_records")
+    lesson = relationship("Lesson", back_populates="progress_records")
+
+    def __repr__(self):
+        return f"<Progress {self.student_id} -> {self.lesson_id}>"
+
+
+class StudyStreak(Base):
+    __tablename__ = "study_streaks"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    student_id = Column(String(36), ForeignKey("users.id"), nullable=False, unique=True)
+    current_streak = Column(Integer, default=0)
+    longest_streak = Column(Integer, default=0)
+    last_study_date = Column(DateTime, nullable=True)
+    total_study_days = Column(Integer, default=0)
+
+    # Relationships
+    student = relationship("User")
+
+    def __repr__(self):
+        return f"<StudyStreak {self.student_id}: {self.current_streak} days>"

app/models/quiz.py

@@ -0,0 +1,83 @@
+"""Quiz and assessment models."""
+
+from datetime import datetime
+from enum import Enum as PyEnum
+from sqlalchemy import Column, String, Boolean, DateTime, Text, Integer, ForeignKey, Float, JSON
+from sqlalchemy.orm import relationship
+from uuid import uuid4
+from app.database import Base
+
+
+class QuestionType(str, PyEnum):
+    MULTIPLE_CHOICE = "multiple_choice"
+    TRUE_FALSE = "true_false"
+    SHORT_ANSWER = "short_answer"
+
+
+class Quiz(Base):
+    __tablename__ = "quizzes"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    lesson_id = Column(String(36), ForeignKey("lessons.id"), nullable=False)
+    title = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    passing_score = Column(Float, default=70.0)
+    time_limit_minutes = Column(Integer, nullable=True)
+    max_attempts = Column(Integer, default=3)
+    is_ai_generated = Column(Boolean, default=False)
+    is_published = Column(Boolean, default=False)
+
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    # Relationships
+    lesson = relationship("Lesson", back_populates="quizzes")
+    questions = relationship("QuizQuestion", back_populates="quiz", cascade="all, delete-orphan")
+    attempts = relationship("QuizAttempt", back_populates="quiz", cascade="all, delete-orphan")
+
+    def __repr__(self):
+        return f"<Quiz {self.title}>"
+
+
+class QuizQuestion(Base):
+    __tablename__ = "quiz_questions"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    quiz_id = Column(String(36), ForeignKey("quizzes.id"), nullable=False)
+    question_type = Column(String(50), default=QuestionType.MULTIPLE_CHOICE)
+    question_text = Column(Text, nullable=False)
+    options = Column(JSON, nullable=True)  # List of options for MCQ
+    correct_answer = Column(Text, nullable=False)
+    explanation = Column(Text, nullable=True)
+    points = Column(Integer, default=1)
+    order_index = Column(Integer, default=0)
+
+    # Relationships
+    quiz = relationship("Quiz", back_populates="questions")
+
+    def __repr__(self):
+        return f"<QuizQuestion {self.id}>"
+
+
+class QuizAttempt(Base):
+    __tablename__ = "quiz_attempts"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    quiz_id = Column(String(36), ForeignKey("quizzes.id"), nullable=False)
+    student_id = Column(String(36), ForeignKey("users.id"), nullable=False)
+    score = Column(Float, default=0.0)
+    passed = Column(Boolean, default=False)
+    answers = Column(JSON, nullable=True)  # Student's answers
+    time_taken_seconds = Column(Integer, nullable=True)
+
+    # Timestamps
+    started_at = Column(DateTime, default=datetime.utcnow)
+    completed_at = Column(DateTime, nullable=True)
+
+    # Relationships
+    quiz = relationship("Quiz", back_populates="attempts")
+    student = relationship("User", back_populates="quiz_attempts")
+
+    def __repr__(self):
+        return f"<QuizAttempt {self.student_id} -> {self.quiz_id}>"

app/models/user.py

@@ -0,0 +1,43 @@
+"""User model for authentication and profiles."""
+
+from datetime import datetime
+from enum import Enum as PyEnum
+from sqlalchemy import Column, String, Boolean, DateTime, Enum, Text
+from sqlalchemy.orm import relationship
+from uuid import uuid4
+from app.database import Base
+
+
+class UserRole(str, PyEnum):
+    STUDENT = "student"
+    INSTRUCTOR = "instructor"
+    ADMIN = "admin"
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    email = Column(String(255), unique=True, nullable=False, index=True)
+    hashed_password = Column(String(255), nullable=False)
+    full_name = Column(String(255), nullable=False)
+    avatar_url = Column(String(500), nullable=True)
+    role = Column(Enum(UserRole), default=UserRole.STUDENT, nullable=False)
+    is_active = Column(Boolean, default=True)
+    is_verified = Column(Boolean, default=False)
+    bio = Column(Text, nullable=True)
+
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    last_login = Column(DateTime, nullable=True)
+
+    # Relationships
+    enrollments = relationship("Enrollment", back_populates="student", cascade="all, delete-orphan")
+    progress_records = relationship("Progress", back_populates="student", cascade="all, delete-orphan")
+    quiz_attempts = relationship("QuizAttempt", back_populates="student", cascade="all, delete-orphan")
+    forum_posts = relationship("ForumPost", back_populates="author", cascade="all, delete-orphan")
+    forum_comments = relationship("ForumComment", back_populates="author", cascade="all, delete-orphan")
+
+    def __repr__(self):
+        return f"<User {self.email}>"

app/routes/admin.py

@@ -0,0 +1,244 @@
+"""Admin routes for platform management."""
+
+from typing import List, Optional
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Form, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func
+from app.database import get_db
+from app.models.user import User, UserRole
+from app.models.course import Course, Module, Lesson
+from app.models.progress import Enrollment, Progress
+from app.models.quiz import QuizAttempt
+from app.schemas.user import UserResponse, UserBrief
+from app.dependencies import require_admin
+from pydantic import BaseModel
+from datetime import datetime, timedelta
+
+
+router = APIRouter(prefix="/admin", tags=["Admin"])
+
+
+class PlatformStats(BaseModel):
+    total_users: int
+    total_students: int
+    total_instructors: int
+    total_admins: int
+    total_courses: int
+    published_courses: int
+    total_enrollments: int
+    total_lessons_completed: int
+    active_users_7d: int
+
+
+class UserListItem(BaseModel):
+    id: str
+    email: str
+    full_name: str
+    role: UserRole
+    is_active: bool
+    created_at: datetime
+    last_login: Optional[datetime]
+    enrollments_count: int = 0
+
+    class Config:
+        from_attributes = True
+
+
+class UpdateUserRole(BaseModel):
+    role: UserRole
+
+
+# ─── Platform Analytics ─────────────────────────────────
+
+@router.get("/stats", response_model=PlatformStats)
+async def get_platform_stats(
+    current_user: User = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get platform-wide statistics."""
+    try:
+        total_users = await db.execute(select(func.count(User.id)))
+        students = await db.execute(
+            select(func.count(User.id)).where(User.role == UserRole.STUDENT)
+        )
+        instructors = await db.execute(
+            select(func.count(User.id)).where(User.role == UserRole.INSTRUCTOR)
+        )
+        admins = await db.execute(
+            select(func.count(User.id)).where(User.role == UserRole.ADMIN)
+        )
+        total_courses = await db.execute(select(func.count(Course.id)))
+        published_courses = await db.execute(
+            select(func.count(Course.id)).where(Course.is_published == True)
+        )
+        total_enrollments = await db.execute(select(func.count(Enrollment.id)))
+        total_completed = await db.execute(
+            select(func.count(Progress.id)).where(Progress.is_completed == True)
+        )
+        week_ago = datetime.utcnow() - timedelta(days=7)
+        active_users = await db.execute(
+            select(func.count(User.id)).where(User.last_login >= week_ago)
+        )
+        return PlatformStats(
+            total_users=total_users.scalar() or 0,
+            total_students=students.scalar() or 0,
+            total_instructors=instructors.scalar() or 0,
+            total_admins=admins.scalar() or 0,
+            total_courses=total_courses.scalar() or 0,
+            published_courses=published_courses.scalar() or 0,
+            total_enrollments=total_enrollments.scalar() or 0,
+            total_lessons_completed=total_completed.scalar() or 0,
+            active_users_7d=active_users.scalar() or 0,
+        )
+    except Exception as e:
+        print(f"⚠️  Could not fetch admin stats: {e}")
+        return PlatformStats(
+            total_users=0, total_students=0, total_instructors=0, total_admins=0,
+            total_courses=0, published_courses=0, total_enrollments=0,
+            total_lessons_completed=0, active_users_7d=0,
+        )
+
+
+# ─── User Management ────────────────────────────────────
+
+@router.get("/users", response_model=List[UserListItem])
+async def list_users(
+    role: Optional[UserRole] = None,
+    search: Optional[str] = None,
+    limit: int = Query(default=50, le=100),
+    offset: int = 0,
+    current_user: User = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    """List all users with optional filtering."""
+    try:
+        query = select(User)
+
+        if role:
+            query = query.where(User.role == role)
+
+        if search:
+            query = query.where(
+                (User.email.ilike(f"%{search}%")) | (User.full_name.ilike(f"%{search}%"))
+            )
+
+        query = query.order_by(User.created_at.desc()).limit(limit).offset(offset)
+        result = await db.execute(query)
+        users = result.scalars().all()
+
+        # Get enrollment counts
+        user_list = []
+        for user in users:
+            enrollment_count = await db.execute(
+                select(func.count(Enrollment.id)).where(Enrollment.student_id == user.id)
+            )
+            user_list.append(
+                UserListItem(
+                    **UserResponse.model_validate(user).model_dump(),
+                    enrollments_count=enrollment_count.scalar() or 0,
+                )
+            )
+
+        return user_list
+    except Exception as e:
+        print(f"⚠️  Could not fetch users: {e}")
+        return []
+
+
+@router.patch("/users/{user_id}/role", response_model=UserResponse)
+async def update_user_role(
+    user_id: str,
+    data: UpdateUserRole,
+    current_user: User = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update a user's role."""
+    if user_id == current_user.id:
+        raise HTTPException(status_code=400, detail="Cannot change your own role")
+
+    try:
+        result = await db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+
+        if not user:
+            raise HTTPException(status_code=404, detail="User not found")
+
+        user.role = data.role
+        await db.commit()
+        await db.refresh(user)
+
+        return UserResponse.model_validate(user)
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"⚠️  Could not update user role: {e}")
+        raise HTTPException(status_code=503, detail="Database unavailable in demo mode")
+
+
+@router.patch("/users/{user_id}/status")
+async def toggle_user_status(
+    user_id: str,
+    current_user: User = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    """Activate/deactivate a user."""
+    if user_id == current_user.id:
+        raise HTTPException(status_code=400, detail="Cannot deactivate yourself")
+
+    try:
+        result = await db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+
+        if not user:
+            raise HTTPException(status_code=404, detail="User not found")
+
+        user.is_active = not user.is_active
+        await db.commit()
+
+        return {"id": user.id, "is_active": user.is_active}
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"⚠️  Could not toggle user status: {e}")
+        raise HTTPException(status_code=503, detail="Database unavailable in demo mode")
+
+
+# ─── Course Management ──────────────────────────────────
+
+@router.get("/courses/analytics")
+async def get_course_analytics(
+    current_user: User = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get analytics for all courses."""
+    try:
+        courses_result = await db.execute(select(Course))
+        courses = courses_result.scalars().all()
+
+        analytics = []
+        for course in courses:
+            enrollment_count = await db.execute(
+                select(func.count(Enrollment.id)).where(Enrollment.course_id == course.id)
+            )
+            completion_count = await db.execute(
+                select(func.count(Enrollment.id)).where(
+                    Enrollment.course_id == course.id,
+                    Enrollment.is_completed == True,
+                )
+            )
+
+            analytics.append({
+                "course_id": course.id,
+                "title": course.title,
+                "is_published": course.is_published,
+                "enrollments": enrollment_count.scalar() or 0,
+                "completions": completion_count.scalar() or 0,
+                "completion_rate": (
+                    round((completion_count.scalar() or 0) / (enrollment_count.scalar() or 1) * 100, 1)
+                ),
+            })
+
+        return analytics
+    except Exception as e:
+        print(f"⚠️  Could not fetch course analytics: {e}")
+        return []

app/routes/auth.py

@@ -0,0 +1,292 @@
+"""Authentication routes."""
+
+from datetime import datetime
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from app.database import get_db
+from app.models.user import User
+from app.schemas.user import (
+    UserCreate,
+    UserLogin,
+    UserResponse,
+    TokenResponse,
+    RefreshTokenRequest,
+)
+from app.services.auth import (
+    hash_password,
+    verify_password,
+    create_tokens,
+    decode_token,
+)
+from app.dependencies import get_current_user
+
+
+router = APIRouter(prefix="/auth", tags=["Authentication"])
+
+# Demo users for testing without database
+DEMO_USERS = {
+    "admin@demo.com": {
+        "password": "admin123",
+        "full_name": "Admin Demo",
+        "role": "admin",
+        "id": "admin-demo-001",
+    },
+    "instructor@demo.com": {
+        "password": "instructor123",
+        "full_name": "Instructor Demo",
+        "role": "instructor",
+        "id": "instructor-demo-001",
+    },
+    "student@demo.com": {
+        "password": "student123",
+        "full_name": "Student Demo",
+        "role": "student",
+        "id": "student-demo-001",
+    },
+}
+
+
+@router.post("/register", response_model=TokenResponse, status_code=status.HTTP_201_CREATED)
+async def register(
+    data: UserCreate,
+    db: AsyncSession = Depends(get_db),
+):
+    """Register a new user."""
+    try:
+        # Check if email exists
+        result = await db.execute(select(User).where(User.email == data.email))
+        if result.scalar_one_or_none():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Email already registered",
+            )
+
+        # Create user
+        user = User(
+            email=data.email,
+            hashed_password=hash_password(data.password),
+            full_name=data.full_name,
+            role=data.role,  # Use role from request (student or instructor)
+        )
+        db.add(user)
+        await db.commit()
+        await db.refresh(user)
+
+        # Create tokens
+        tokens = create_tokens(user.id, user.email, user.role.value)
+
+        return TokenResponse(
+            **tokens,
+            user=UserResponse.model_validate(user),
+        )
+    except Exception as e:
+        # Fallback to demo mode if database is not available
+        if "password authentication failed" in str(e) or "connect" in str(e).lower():
+            # Demo mode: Create demo user
+            demo_id = f"demo-{hash(data.email)}"
+            tokens = create_tokens(demo_id, data.email, "student")
+            
+            demo_user = UserResponse(
+                id=demo_id,
+                email=data.email,
+                full_name=data.full_name,
+                avatar_url=None,
+                role="student",
+                is_active=True,
+                is_verified=True,
+                bio=None,
+                created_at=datetime.utcnow(),
+                last_login=None,
+            )
+            
+            return TokenResponse(
+                **tokens,
+                user=demo_user,
+            )
+        raise
+
+
+@router.post("/login", response_model=TokenResponse)
+async def login(
+    data: UserLogin,
+    db: AsyncSession = Depends(get_db),
+):
+    """Login and get tokens."""
+    try:
+        # Try database first
+        try:
+            # Find user in database
+            result = await db.execute(select(User).where(User.email == data.email))
+            user = result.scalar_one_or_none()
+
+            if not user or not verify_password(data.password, user.hashed_password):
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Invalid email or password",
+                )
+
+            if not user.is_active:
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail="Account is deactivated",
+                )
+
+            # Update last login
+            user.last_login = datetime.utcnow()
+            await db.commit()
+            await db.refresh(user)
+
+            # Create tokens
+            tokens = create_tokens(user.id, user.email, user.role.value)
+
+            return TokenResponse(
+                **tokens,
+                user=UserResponse.model_validate(user),
+            )
+        except HTTPException:
+            raise
+        except Exception as db_error:
+            # Database failed, fall back to demo mode
+            print(f"⚠️  Database error during login: {db_error}")
+            raise db_error
+            
+    except HTTPException:
+        # Let HTTP exceptions pass through
+        raise
+    except Exception as e:
+        # Fallback to demo mode if database is not available
+        error_str = str(e).lower()
+        if "password authentication failed" in error_str or "connect" in error_str or "cannot connect" in error_str:
+            # Check demo users
+            if data.email in DEMO_USERS:
+                demo_user = DEMO_USERS[data.email]
+                if demo_user["password"] != data.password:
+                    raise HTTPException(
+                        status_code=status.HTTP_401_UNAUTHORIZED,
+                        detail="Invalid email or password (demo mode)",
+                    )
+                
+                tokens = create_tokens(demo_user["id"], data.email, demo_user["role"])
+                return TokenResponse(
+                    **tokens,
+                    user=UserResponse(
+                        id=demo_user["id"],
+                        email=data.email,
+                        full_name=demo_user["full_name"],
+                        avatar_url=None,
+                        role=demo_user["role"],
+                        is_active=True,
+                        is_verified=True,
+                        bio=None,
+                        created_at=datetime.utcnow(),
+                        last_login=None,
+                    ),
+                )
+            
+            # Any other credentials work in demo mode
+            user_id = f"demo-user-{hash(data.email)}"
+            tokens = create_tokens(user_id, data.email, "student")
+            return TokenResponse(
+                **tokens,
+                user=UserResponse(
+                    id=user_id,
+                    email=data.email,
+                    full_name="Demo User",
+                    avatar_url=None,
+                    role="student",
+                    is_active=True,
+                    is_verified=True,
+                    bio=None,
+                    created_at=datetime.utcnow(),
+                    last_login=None,
+                ),
+            )
+        
+        # For other errors, still try demo mode
+        print(f"⚠️  Login error: {e}")
+        
+        # Check demo users
+        if data.email in DEMO_USERS:
+            demo_user = DEMO_USERS[data.email]
+            if demo_user["password"] != data.password:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Invalid email or password",
+                )
+            
+            tokens = create_tokens(demo_user["id"], data.email, demo_user["role"])
+            return TokenResponse(
+                **tokens,
+                user=UserResponse(
+                    id=demo_user["id"],
+                    email=data.email,
+                    full_name=demo_user["full_name"],
+                    avatar_url=None,
+                    role=demo_user["role"],
+                    is_active=True,
+                    is_verified=True,
+                    bio=None,
+                    created_at=datetime.utcnow(),
+                    last_login=None,
+                ),
+            )
+        
+        # Generic fallback user
+        user_id = f"demo-user-{hash(data.email)}"
+        tokens = create_tokens(user_id, data.email, "student")
+        return TokenResponse(
+            **tokens,
+            user=UserResponse(
+                id=user_id,
+                email=data.email,
+                full_name="Demo User",
+                avatar_url=None,
+                role="student",
+                is_active=True,
+                is_verified=True,
+                bio=None,
+                created_at=datetime.utcnow(),
+                last_login=None,
+            ),
+        )
+    
+
+@router.post("/refresh", response_model=TokenResponse)
+async def refresh_token(
+    data: RefreshTokenRequest,
+    db: AsyncSession = Depends(get_db),
+):
+    """Refresh access token using refresh token."""
+    payload = decode_token(data.refresh_token)
+
+    if not payload or payload.get("type") != "refresh":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid refresh token",
+        )
+
+    user_id = payload.get("sub")
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+
+    if not user or not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found or inactive",
+        )
+
+    tokens = create_tokens(user.id, user.email, user.role.value)
+
+    return TokenResponse(
+        **tokens,
+        user=UserResponse.model_validate(user),
+    )
+
+
+@router.get("/me", response_model=UserResponse)
+async def get_me(
+    current_user: User = Depends(get_current_user),
+):
+    """Get current user profile."""
+    return UserResponse.model_validate(current_user)

app/routes/courses.py

@@ -0,0 +1,459 @@
+"""Course management routes."""
+
+import os
+import aiofiles
+from typing import List
+from fastapi import APIRouter, Depends, HTTPException, status, UploadFile, File
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func
+from sqlalchemy.orm import selectinload
+from app.database import get_db
+from app.models.user import User, UserRole
+from app.models.course import Course, Module, Lesson
+from app.models.progress import Enrollment
+from app.schemas.course import (
+    CourseCreate,
+    CourseUpdate,
+    CourseResponse,
+    CourseBrief,
+    CourseWithModules,
+    ModuleCreate,
+    ModuleUpdate,
+    ModuleResponse,
+    ModuleWithLessons,
+    LessonCreate,
+    LessonUpdate,
+    LessonResponse,
+)
+from app.schemas.progress import EnrollmentWithStudent
+from app.dependencies import get_current_user, require_instructor
+from app.config import settings
+from app.services.tutor import tutor_service
+
+
+router = APIRouter(prefix="/courses", tags=["Courses"])
+
+
+# ─── Courses ─────────────────────────────────────────────
+
+@router.get("", response_model=List[CourseBrief])
+async def list_courses(
+    published_only: bool = True,
+    db: AsyncSession = Depends(get_db),
+):
+    """List all courses (public endpoint)."""
+    try:
+        query = select(Course).order_by(Course.order_index)
+        if published_only:
+            query = query.where(Course.is_published == True)
+
+        result = await db.execute(query)
+        return [CourseBrief.model_validate(c) for c in result.scalars().all()]
+    except Exception as e:
+        print(f"⚠️  Could not fetch courses: {e}")
+        return []
+
+
+@router.get("/{course_id}", response_model=CourseWithModules)
+async def get_course(
+    course_id: str,
+    db: AsyncSession = Depends(get_db),
+):
+    """Get course with modules and lessons."""
+    try:
+        result = await db.execute(
+            select(Course)
+            .options(
+                selectinload(Course.modules).selectinload(Module.lessons),
+                selectinload(Course.enrollments),
+            )
+            .where(Course.id == course_id)
+        )
+        course = result.scalar_one_or_none()
+
+        if not course:
+            raise HTTPException(status_code=404, detail="Course not found")
+
+        # Build response with counts
+        response = CourseWithModules.model_validate(course)
+        response.module_count = len(course.modules)
+        response.enrolled_count = len(course.enrollments)
+        response.modules = [
+            ModuleWithLessons(
+                id=m.id,
+                course_id=m.course_id,
+                title=m.title,
+                description=m.description,
+                order_index=m.order_index,
+                is_published=m.is_published,
+                prerequisite_module_id=m.prerequisite_module_id,
+                created_at=m.created_at,
+                lesson_count=len(m.lessons),
+                lessons=[l for l in m.lessons],
+            )
+            for m in course.modules
+        ]
+        return response
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"⚠️  Could not fetch course {course_id}: {e}")
+        raise HTTPException(status_code=404, detail="Course not found")
+
+
+@router.get("/{course_id}/enrollments", response_model=List[EnrollmentWithStudent])
+async def get_course_enrollments(
+    course_id: str,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get all enrollments for a course (instructor/admin only)."""
+    # Verify course exists and user has permission
+    course_result = await db.execute(select(Course).where(Course.id == course_id))
+    course = course_result.scalar_one_or_none()
+    
+    if not course:
+        raise HTTPException(status_code=404, detail="Course not found")
+    
+    # Only course creator or admin can view enrollments
+    if current_user.role != UserRole.ADMIN and course.created_by != current_user.id:
+        raise HTTPException(status_code=403, detail="Not authorized to view this course's enrollments")
+    
+    # Get enrollments with student data
+    result = await db.execute(
+        select(Enrollment)
+        .options(selectinload(Enrollment.student))
+        .where(Enrollment.course_id == course_id)
+        .order_by(Enrollment.enrolled_at.desc())
+    )
+    enrollments = result.scalars().all()
+    
+    # Build response with student info
+    return [
+        EnrollmentWithStudent(
+            id=e.id,
+            student_id=e.student_id,
+            student_name=e.student.full_name,
+            student_email=e.student.email,
+            course_id=e.course_id,
+            enrolled_at=e.enrolled_at,
+            completed_at=e.completed_at,
+            is_completed=e.is_completed,
+            progress_percentage=e.progress_percentage,
+        )
+        for e in enrollments
+    ]
+
+
+@router.post("", response_model=CourseResponse, status_code=status.HTTP_201_CREATED)
+async def create_course(
+    data: CourseCreate,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Create a new course (instructors/admins only)."""
+    # Check slug uniqueness
+    result = await db.execute(select(Course).where(Course.slug == data.slug))
+    if result.scalar_one_or_none():
+        raise HTTPException(status_code=400, detail="Slug already exists")
+
+    course = Course(**data.model_dump(), created_by=current_user.id)
+    db.add(course)
+    await db.commit()
+    await db.refresh(course)
+
+    return CourseResponse.model_validate(course)
+
+
+@router.patch("/{course_id}", response_model=CourseResponse)
+async def update_course(
+    course_id: str,
+    data: CourseUpdate,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update a course."""
+    result = await db.execute(select(Course).where(Course.id == course_id))
+    course = result.scalar_one_or_none()
+
+    if not course:
+        raise HTTPException(status_code=404, detail="Course not found")
+    
+    # Only course creator or admin can update
+    if current_user.role != UserRole.ADMIN and course.created_by != current_user.id:
+        raise HTTPException(status_code=403, detail="You can only update your own courses")
+
+    for field, value in data.model_dump(exclude_unset=True).items():
+        setattr(course, field, value)
+
+    await db.commit()
+    await db.refresh(course)
+
+    return CourseResponse.model_validate(course)
+
+
+@router.delete("/{course_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_course(
+    course_id: str,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete a course."""
+    result = await db.execute(select(Course).where(Course.id == course_id))
+    course = result.scalar_one_or_none()
+
+    if not course:
+        raise HTTPException(status_code=404, detail="Course not found")
+    
+    # Only course creator or admin can delete
+    if current_user.role != UserRole.ADMIN and course.created_by != current_user.id:
+        raise HTTPException(status_code=403, detail="You can only delete your own courses")
+
+    await db.delete(course)
+    await db.commit()
+
+
+# ─── Modules ─────────────────────────────────────────────
+
+@router.post("/{course_id}/modules", response_model=ModuleResponse, status_code=status.HTTP_201_CREATED)
+async def create_module(
+    course_id: str,
+    data: ModuleCreate,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Create a new module in a course."""
+    result = await db.execute(select(Course).where(Course.id == course_id))
+    course = result.scalar_one_or_none()
+    if not course:
+        raise HTTPException(status_code=404, detail="Course not found")
+    
+    # Only course creator or admin can add modules
+    if current_user.role != UserRole.ADMIN and course.created_by != current_user.id:
+        raise HTTPException(status_code=403, detail="You can only add modules to your own courses")
+
+    module = Module(**data.model_dump(), course_id=course_id)
+    db.add(module)
+    await db.commit()
+    await db.refresh(module)
+
+    return ModuleResponse.model_validate(module)
+
+
+@router.patch("/modules/{module_id}", response_model=ModuleResponse)
+async def update_module(
+    module_id: str,
+    data: ModuleUpdate,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update a module."""
+    result = await db.execute(
+        select(Module).options(selectinload(Module.course)).where(Module.id == module_id)
+    )
+    module = result.scalar_one_or_none()
+
+    if not module:
+        raise HTTPException(status_code=404, detail="Module not found")
+    
+    # Only course creator or admin can update modules
+    if current_user.role != UserRole.ADMIN and module.course.created_by != current_user.id:
+        raise HTTPException(status_code=403, detail="You can only update modules in your own courses")
+
+    for field, value in data.model_dump(exclude_unset=True).items():
+        setattr(module, field, value)
+
+    await db.commit()
+    await db.refresh(module)
+
+    return ModuleResponse.model_validate(module)
+
+
+@router.delete("/modules/{module_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_module(
+    module_id: str,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete a module and all its lessons."""
+    result = await db.execute(
+        select(Module).options(selectinload(Module.course)).where(Module.id == module_id)
+    )
+    module = result.scalar_one_or_none()
+
+    if not module:
+        raise HTTPException(status_code=404, detail="Module not found")
+    
+    # Only course creator or admin can delete modules
+    if current_user.role != UserRole.ADMIN and module.course.created_by != current_user.id:
+        raise HTTPException(status_code=403, detail="You can only delete modules from your own courses")
+
+    await db.delete(module)
+    await db.commit()
+
+
+# ─── Lessons ─────────────────────────────────────────────
+
+@router.post("/modules/{module_id}/lessons", response_model=LessonResponse, status_code=status.HTTP_201_CREATED)
+async def create_lesson(
+    module_id: str,
+    data: LessonCreate,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Create a new lesson in a module."""
+    result = await db.execute(
+        select(Module).options(selectinload(Module.course)).where(Module.id == module_id)
+    )
+    module = result.scalar_one_or_none()
+    if not module:
+        raise HTTPException(status_code=404, detail="Module not found")
+    
+    # Only course creator or admin can add lessons
+    if current_user.role != UserRole.ADMIN and module.course.created_by != current_user.id:
+        raise HTTPException(status_code=403, detail="You can only add lessons to your own courses")
+
+    lesson = Lesson(**data.model_dump(), module_id=module_id)
+    db.add(lesson)
+    await db.commit()
+    await db.refresh(lesson)
+
+    # Index lesson content for AI tutor (background task)
+    try:
+        await tutor_service.index_lesson_content(
+            lesson_id=str(lesson.id),
+            module_id=str(module_id),
+            title=lesson.title,
+            content_text=lesson.content_text,
+            content_url=lesson.content_url,
+            content_type=lesson.content_type.value if lesson.content_type else "markdown",
+        )
+    except Exception as e:
+        print(f"⚠️  Failed to index lesson content: {e}")
+        # Don't fail the request if indexing fails
+
+    return LessonResponse.model_validate(lesson)
+
+
+@router.get("/lessons/{lesson_id}", response_model=LessonResponse)
+async def get_lesson(
+    lesson_id: str,
+    db: AsyncSession = Depends(get_db),
+):
+    """Get a specific lesson."""
+    try:
+        result = await db.execute(select(Lesson).where(Lesson.id == lesson_id))
+        lesson = result.scalar_one_or_none()
+
+        if not lesson:
+            raise HTTPException(status_code=404, detail="Lesson not found")
+
+        return LessonResponse.model_validate(lesson)
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"⚠️  Could not fetch lesson {lesson_id}: {e}")
+        raise HTTPException(status_code=404, detail="Lesson not found")
+
+
+@router.patch("/lessons/{lesson_id}", response_model=LessonResponse)
+async def update_lesson(
+    lesson_id: str,
+    data: LessonUpdate,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update a lesson."""
+    result = await db.execute(
+        select(Lesson).options(
+            selectinload(Lesson.module).selectinload(Module.course)
+        ).where(Lesson.id == lesson_id)
+    )
+    lesson = result.scalar_one_or_none()
+
+    if not lesson:
+        raise HTTPException(status_code=404, detail="Lesson not found")
+    
+    # Only course creator or admin can update lessons
+    if current_user.role != UserRole.ADMIN and lesson.module.course.created_by != current_user.id:
+        raise HTTPException(status_code=403, detail="You can only update lessons in your own courses")
+
+    for field, value in data.model_dump(exclude_unset=True).items():
+        setattr(lesson, field, value)
+
+    await db.commit()
+    await db.refresh(lesson)
+
+    return LessonResponse.model_validate(lesson)
+
+
+# ─── File Upload ─────────────────────────────────────────
+
+ALLOWED_EXTENSIONS = {".pdf", ".mp4", ".mov", ".avi", ".mkv", ".md", ".txt", ".docx", ".pptx"}
+MAX_FILE_SIZE = settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024  # Convert MB to bytes
+
+
+@router.post("/lessons/upload", status_code=status.HTTP_201_CREATED)
+async def upload_lesson_file(
+    file: UploadFile = File(...),
+    current_user: User = Depends(require_instructor),
+):
+    """Upload a file for a lesson (PDF, video, etc.)."""
+    
+    # Validate file extension
+    ext = os.path.splitext(file.filename)[1].lower()
+    if ext not in ALLOWED_EXTENSIONS:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unsupported file type: {ext}. Allowed: {', '.join(ALLOWED_EXTENSIONS)}",
+        )
+
+    # Check file size
+    content = await file.read()
+    if len(content) > MAX_FILE_SIZE:
+        raise HTTPException(
+            status_code=400,
+            detail=f"File too large. Maximum size: {settings.MAX_UPLOAD_SIZE_MB}MB",
+        )
+
+    # Generate unique filename
+    import uuid
+    from datetime import datetime
+    timestamp = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+    unique_filename = f"{timestamp}_{uuid.uuid4().hex[:8]}_{file.filename}"
+    file_path = os.path.join(settings.UPLOAD_DIR, unique_filename)
+
+    # Save file
+    try:
+        async with aiofiles.open(file_path, "wb") as f:
+            await f.write(content)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to save file: {str(e)}")
+
+    # Return file URL
+    file_url = f"/uploads/{unique_filename}"
+    
+    return {
+        "filename": file.filename,
+        "file_url": file_url,
+        "file_size": len(content),
+        "content_type": file.content_type,
+    }
+
+
+@router.get("/uploads/{filename}")
+async def download_file(filename: str):
+    """Download/view uploaded file."""
+    from fastapi.responses import FileResponse
+    
+    file_path = os.path.join(settings.UPLOAD_DIR, filename)
+    
+    if not os.path.exists(file_path):
+        raise HTTPException(status_code=404, detail="File not found")
+    
+    return FileResponse(
+        file_path,
+        filename=filename,
+        media_type="application/octet-stream",
+    )
+

app/routes/documents.py

@@ -0,0 +1,330 @@
+"""Document management routes for resource library."""
+
+import os
+from typing import List, Optional
+from datetime import datetime
+from fastapi import APIRouter, Depends, HTTPException, status, UploadFile, File
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, and_, or_
+from app.database import get_db
+from app.models.user import User, UserRole
+from app.models.document import Document
+from app.dependencies import get_current_user, require_instructor
+from app.config import settings
+from app.services.tutor import tutor_service
+from pydantic import BaseModel
+import aiofiles
+from uuid import uuid4
+
+
+router = APIRouter(prefix="/documents", tags=["Documents"])
+
+
+# ─── Schemas ─────────────────────────────────────────────
+
+class DocumentMeta(BaseModel):
+    """Metadata stored in document."""
+    course_id: Optional[str] = None
+    module_id: Optional[str] = None
+    lesson_id: Optional[str] = None
+    category: Optional[str] = None
+    tags: Optional[List[str]] = []
+    uploaded_by: Optional[str] = None
+
+
+class DocumentResponse(BaseModel):
+    id: str
+    filename: str
+    file_path: Optional[str] = None
+    chunk_index: int
+    meta: Optional[dict] = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class DocumentBrief(BaseModel):
+    """Grouped document info (one per file, not per chunk)."""
+    id: str
+    filename: str
+    file_path: str
+    category: Optional[str] = None
+    tags: Optional[List[str]] = []
+    chunk_count: int
+    created_at: datetime
+    uploaded_by: Optional[str] = None
+
+
+class DocumentUpload(BaseModel):
+    course_id: Optional[str] = None
+    module_id: Optional[str] = None
+    lesson_id: Optional[str] = None
+    category: Optional[str] = "resource"
+    tags: Optional[List[str]] = []
+
+
+# ─── Document Upload & Management ────────────────────────
+
+@router.post("/upload", response_model=dict)
+async def upload_document(
+    file: UploadFile = File(...),
+    course_id: Optional[str] = None,
+    module_id: Optional[str] = None,
+    lesson_id: Optional[str] = None,
+    category: str = "resource",
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Upload a document for indexing into vector store (instructor only)."""
+    
+    # Validate file type
+    allowed_extensions = [".pdf", ".txt", ".md", ".docx"]
+    file_ext = os.path.splitext(file.filename)[1].lower()
+    if file_ext not in allowed_extensions:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"File type not supported. Allowed: {', '.join(allowed_extensions)}"
+        )
+
+    # Save file to uploads directory
+    file_id = str(uuid4())
+    filename = f"{file_id}_{file.filename}"
+    file_path = os.path.join(settings.UPLOAD_DIR, filename)
+
+    try:
+        async with aiofiles.open(file_path, "wb") as f:
+            content = await file.read()
+            await f.write(content)
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to save file: {str(e)}"
+        )
+
+    # Extract text and create embeddings
+    try:
+        # Read file content
+        if file_ext == ".pdf":
+            from PyPDF2 import PdfReader
+            reader = PdfReader(file_path)
+            text_parts = []
+            for page in reader.pages[:50]:  # Max 50 pages
+                text = page.extract_text()
+                if text:
+                    text_parts.append(text)
+            file_content = "\n\n".join(text_parts)
+        elif file_ext in [".txt", ".md"]:
+            async with aiofiles.open(file_path, "r", encoding="utf-8") as f:
+                file_content = await f.read()
+        else:
+            # For DOCX, would need python-docx library
+            file_content = ""
+
+        if not file_content or len(file_content.strip()) < 50:
+            os.remove(file_path)
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Document content is too short or empty"
+            )
+
+        # Index using tutor service
+        await tutor_service.initialize()
+        
+        # Split into chunks
+        chunks = tutor_service.text_splitter.split_text(file_content)
+        
+        # Create metadata
+        metadata = {
+            "filename": file.filename,
+            "file_path": filename,
+            "uploaded_by": current_user.id,
+            "category": category,
+            "course_id": course_id,
+            "module_id": module_id,
+            "lesson_id": lesson_id,
+        }
+
+        # Create embeddings for each chunk
+        chunk_ids = []
+        for i, chunk in enumerate(chunks):
+            # Get embedding
+            embedding_vector = tutor_service.embeddings.embed_query(chunk)
+            
+            # Save to database
+            doc = Document(
+                content=chunk,
+                embedding=embedding_vector,
+                meta=metadata,
+                filename=file.filename,
+                file_path=filename,
+                chunk_index=i,
+            )
+            db.add(doc)
+            chunk_ids.append(doc.id)
+        
+        await db.commit()
+
+        return {
+            "message": "Document uploaded and indexed successfully",
+            "filename": file.filename,
+            "chunks": len(chunks),
+            "file_path": filename,
+            "chunk_ids": chunk_ids,
+        }
+
+    except Exception as e:
+        # Clean up file on error
+        if os.path.exists(file_path):
+            os.remove(file_path)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to process document: {str(e)}"
+        )
+
+
+@router.get("", response_model=List[DocumentBrief])
+async def list_documents(
+    course_id: Optional[str] = None,
+    module_id: Optional[str] = None,
+    lesson_id: Optional[str] = None,
+    category: Optional[str] = None,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """List all documents (grouped by filename)."""
+    query = select(Document)
+
+    # Apply filters using JSONB operators
+    filters = []
+    if course_id:
+        filters.append(Document.meta["course_id"].astext == course_id)
+    if module_id:
+        filters.append(Document.meta["module_id"].astext == module_id)
+    if lesson_id:
+        filters.append(Document.meta["lesson_id"].astext == lesson_id)
+    if category:
+        filters.append(Document.meta["category"].astext == category)
+
+    if filters:
+        query = query.where(and_(*filters))
+
+    result = await db.execute(query.order_by(Document.created_at.desc()))
+    documents = result.scalars().all()
+
+    # Group by filename
+    grouped = {}
+    for doc in documents:
+        if doc.filename not in grouped:
+            grouped[doc.filename] = {
+                "id": doc.id,
+                "filename": doc.filename,
+                "file_path": doc.file_path or "",
+                "category": doc.meta.get("category") if doc.meta else None,
+                "tags": doc.meta.get("tags", []) if doc.meta else [],
+                "chunk_count": 0,
+                "created_at": doc.created_at,
+                "uploaded_by": doc.meta.get("uploaded_by") if doc.meta else None,
+            }
+        grouped[doc.filename]["chunk_count"] += 1
+
+    return list(grouped.values())
+
+
+@router.get("/{document_id}", response_model=DocumentResponse)
+async def get_document(
+    document_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get document details."""
+    result = await db.execute(
+        select(Document).where(Document.id == document_id)
+    )
+    document = result.scalar_one_or_none()
+    if not document:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Document not found"
+        )
+    return document
+
+
+@router.delete("/file/{filename}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_document_file(
+    filename: str,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete all chunks of a document file (instructor only)."""
+    # Find all chunks with this filename
+    result = await db.execute(
+        select(Document).where(Document.filename == filename)
+    )
+    documents = result.scalars().all()
+    
+    if not documents:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Document not found"
+        )
+
+    # Delete file from disk
+    file_path = os.path.join(settings.UPLOAD_DIR, documents[0].file_path)
+    if os.path.exists(file_path):
+        try:
+            os.remove(file_path)
+        except Exception as e:
+            print(f"Warning: Could not delete file {file_path}: {e}")
+
+    # Delete all chunks from database
+    for doc in documents:
+        await db.delete(doc)
+    
+    await db.commit()
+
+
+@router.post("/search", response_model=List[DocumentResponse])
+async def search_documents(
+    query: str,
+    top_k: int = 5,
+    course_id: Optional[str] = None,
+    module_id: Optional[str] = None,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Semantic search across documents using vector similarity."""
+    await tutor_service.initialize()
+
+    try:
+        # Get query embedding
+        query_embedding = tutor_service.embeddings.embed_query(query)
+
+        # Build filter
+        filter_parts = []
+        if course_id:
+            filter_parts.append(Document.meta["course_id"].astext == course_id)
+        if module_id:
+            filter_parts.append(Document.meta["module_id"].astext == module_id)
+
+        # Perform vector similarity search
+        query_obj = select(Document)
+        if filter_parts:
+            query_obj = query_obj.where(and_(*filter_parts))
+        
+        # Order by cosine distance
+        query_obj = query_obj.order_by(
+            Document.embedding.cosine_distance(query_embedding)
+        ).limit(top_k)
+
+        result = await db.execute(query_obj)
+        documents = result.scalars().all()
+
+        return documents
+
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Search failed: {str(e)}"
+        )

app/routes/forum.py

@@ -0,0 +1,446 @@
+"""Forum and discussion routes."""
+
+from typing import List, Optional
+from datetime import datetime
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, and_, or_, func, desc
+from sqlalchemy.orm import selectinload
+from app.database import get_db
+from app.models.user import User
+from app.models.forum import ForumPost, ForumComment
+from app.dependencies import get_current_user
+from pydantic import BaseModel
+
+
+router = APIRouter(prefix="/forum", tags=["Forum"])
+
+
+# ─── Schemas ─────────────────────────────────────────────
+
+class PostCreate(BaseModel):
+    module_id: Optional[str] = None
+    title: str
+    content: str
+
+
+class PostUpdate(BaseModel):
+    title: Optional[str] = None
+    content: Optional[str] = None
+    is_pinned: Optional[bool] = None
+    is_resolved: Optional[bool] = None
+
+
+class CommentCreate(BaseModel):
+    content: str
+    parent_id: Optional[str] = None
+
+
+class CommentUpdate(BaseModel):
+    content: Optional[str] = None
+    is_accepted_answer: Optional[bool] = None
+
+
+class UserBrief(BaseModel):
+    id: str
+    full_name: str
+    avatar_url: Optional[str] = None
+    role: str
+
+    class Config:
+        from_attributes = True
+
+
+class CommentResponse(BaseModel):
+    id: str
+    post_id: str
+    author_id: str
+    parent_id: Optional[str] = None
+    content: str
+    is_accepted_answer: bool
+    upvotes: int
+    created_at: datetime
+    updated_at: datetime
+    author: UserBrief
+
+    class Config:
+        from_attributes = True
+
+
+class PostResponse(BaseModel):
+    id: str
+    module_id: Optional[str] = None
+    author_id: str
+    title: str
+    content: str
+    is_pinned: bool
+    is_resolved: bool
+    upvotes: int
+    view_count: int
+    created_at: datetime
+    updated_at: datetime
+    author: UserBrief
+
+    class Config:
+        from_attributes = True
+
+
+class PostWithComments(PostResponse):
+    comments: List[CommentResponse] = []
+    comment_count: int = 0
+
+
+class PostBrief(BaseModel):
+    id: str
+    module_id: Optional[str] = None
+    title: str
+    is_pinned: bool
+    is_resolved: bool
+    upvotes: int
+    view_count: int
+    created_at: datetime
+    author: UserBrief
+    comment_count: int = 0
+
+    class Config:
+        from_attributes = True
+
+
+# ─── Forum Posts ─────────────────────────────────────────
+
+@router.post("/posts", response_model=PostResponse, status_code=status.HTTP_201_CREATED)
+async def create_post(
+    data: PostCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Create a new forum post."""
+    post = ForumPost(
+        module_id=data.module_id,
+        author_id=current_user.id,
+        title=data.title,
+        content=data.content,
+    )
+    db.add(post)
+    await db.commit()
+    await db.refresh(post, ["author"])
+    return post
+
+
+@router.get("/posts", response_model=List[PostBrief])
+async def list_posts(
+    module_id: Optional[str] = None,
+    search: Optional[str] = None,
+    resolved: Optional[bool] = None,
+    skip: int = 0,
+    limit: int = 50,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """List forum posts with filters."""
+    query = select(ForumPost).options(selectinload(ForumPost.author))
+
+    # Filters
+    if module_id:
+        query = query.where(ForumPost.module_id == module_id)
+    
+    if search:
+        query = query.where(
+            or_(
+                ForumPost.title.ilike(f"%{search}%"),
+                ForumPost.content.ilike(f"%{search}%")
+            )
+        )
+    
+    if resolved is not None:
+        query = query.where(ForumPost.is_resolved == resolved)
+
+    # Order: pinned first, then by creation date
+    query = query.order_by(
+        desc(ForumPost.is_pinned),
+        desc(ForumPost.created_at)
+    ).offset(skip).limit(limit)
+
+    result = await db.execute(query)
+    posts = result.scalars().all()
+
+    # Get comment counts
+    posts_with_counts = []
+    for post in posts:
+        comment_count_result = await db.execute(
+            select(func.count(ForumComment.id)).where(ForumComment.post_id == post.id)
+        )
+        comment_count = comment_count_result.scalar() or 0
+        
+        post_dict = {
+            "id": post.id,
+            "module_id": post.module_id,
+            "title": post.title,
+            "is_pinned": post.is_pinned,
+            "is_resolved": post.is_resolved,
+            "upvotes": post.upvotes,
+            "view_count": post.view_count,
+            "created_at": post.created_at,
+            "author": post.author,
+            "comment_count": comment_count,
+        }
+        posts_with_counts.append(post_dict)
+
+    return posts_with_counts
+
+
+@router.get("/posts/{post_id}", response_model=PostWithComments)
+async def get_post(
+    post_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get post details with comments."""
+    result = await db.execute(
+        select(ForumPost)
+        .options(
+            selectinload(ForumPost.author),
+            selectinload(ForumPost.comments).selectinload(ForumComment.author)
+        )
+        .where(ForumPost.id == post_id)
+    )
+    post = result.scalar_one_or_none()
+    if not post:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Post not found"
+        )
+
+    # Increment view count
+    post.view_count += 1
+    await db.commit()
+    await db.refresh(post)
+
+    # Return post with comment count
+    return {
+        **{k: getattr(post, k) for k in [
+            "id", "module_id", "author_id", "title", "content",
+            "is_pinned", "is_resolved", "upvotes", "view_count",
+            "created_at", "updated_at"
+        ]},
+        "author": post.author,
+        "comments": sorted(post.comments, key=lambda c: c.created_at),
+        "comment_count": len(post.comments),
+    }
+
+
+@router.put("/posts/{post_id}", response_model=PostResponse)
+async def update_post(
+    post_id: str,
+    data: PostUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update a forum post."""
+    result = await db.execute(
+        select(ForumPost).where(ForumPost.id == post_id)
+    )
+    post = result.scalar_one_or_none()
+    if not post:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Post not found"
+        )
+
+    # Check permissions (author or instructor)
+    if post.author_id != current_user.id and current_user.role.value != "instructor":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Not authorized to edit this post"
+        )
+
+    # Update fields
+    for field, value in data.model_dump(exclude_unset=True).items():
+        setattr(post, field, value)
+
+    post.updated_at = datetime.utcnow()
+    await db.commit()
+    await db.refresh(post, ["author"])
+    return post
+
+
+@router.delete("/posts/{post_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_post(
+    post_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete a forum post."""
+    result = await db.execute(
+        select(ForumPost).where(ForumPost.id == post_id)
+    )
+    post = result.scalar_one_or_none()
+    if not post:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Post not found"
+        )
+
+    # Check permissions (author or instructor)
+    if post.author_id != current_user.id and current_user.role.value != "instructor":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Not authorized to delete this post"
+        )
+
+    await db.delete(post)
+    await db.commit()
+
+
+@router.post("/posts/{post_id}/upvote", response_model=PostResponse)
+async def upvote_post(
+    post_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Upvote a post."""
+    result = await db.execute(
+        select(ForumPost).where(ForumPost.id == post_id)
+    )
+    post = result.scalar_one_or_none()
+    if not post:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Post not found"
+        )
+
+    post.upvotes += 1
+    await db.commit()
+    await db.refresh(post, ["author"])
+    return post
+
+
+# ─── Forum Comments ──────────────────────────────────────
+
+@router.post("/posts/{post_id}/comments", response_model=CommentResponse, status_code=status.HTTP_201_CREATED)
+async def create_comment(
+    post_id: str,
+    data: CommentCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Create a comment on a post."""
+    # Verify post exists
+    post_result = await db.execute(
+        select(ForumPost).where(ForumPost.id == post_id)
+    )
+    post = post_result.scalar_one_or_none()
+    if not post:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Post not found"
+        )
+
+    # If parent_id provided, verify it exists
+    if data.parent_id:
+        parent_result = await db.execute(
+            select(ForumComment).where(ForumComment.id == data.parent_id)
+        )
+        parent = parent_result.scalar_one_or_none()
+        if not parent or parent.post_id != post_id:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Parent comment not found"
+            )
+
+    comment = ForumComment(
+        post_id=post_id,
+        author_id=current_user.id,
+        parent_id=data.parent_id,
+        content=data.content,
+    )
+    db.add(comment)
+    await db.commit()
+    await db.refresh(comment, ["author"])
+    return comment
+
+
+@router.put("/comments/{comment_id}", response_model=CommentResponse)
+async def update_comment(
+    comment_id: str,
+    data: CommentUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update a comment."""
+    result = await db.execute(
+        select(ForumComment).where(ForumComment.id == comment_id)
+    )
+    comment = result.scalar_one_or_none()
+    if not comment:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Comment not found"
+        )
+
+    # Check permissions
+    if comment.author_id != current_user.id and current_user.role.value != "instructor":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Not authorized to edit this comment"
+        )
+
+    # Update fields
+    for field, value in data.model_dump(exclude_unset=True).items():
+        setattr(comment, field, value)
+
+    comment.updated_at = datetime.utcnow()
+    await db.commit()
+    await db.refresh(comment, ["author"])
+    return comment
+
+
+@router.delete("/comments/{comment_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_comment(
+    comment_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete a comment."""
+    result = await db.execute(
+        select(ForumComment).where(ForumComment.id == comment_id)
+    )
+    comment = result.scalar_one_or_none()
+    if not comment:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Comment not found"
+        )
+
+    # Check permissions
+    if comment.author_id != current_user.id and current_user.role.value != "instructor":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Not authorized to delete this comment"
+        )
+
+    await db.delete(comment)
+    await db.commit()
+
+
+@router.post("/comments/{comment_id}/upvote", response_model=CommentResponse)
+async def upvote_comment(
+    comment_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Upvote a comment."""
+    result = await db.execute(
+        select(ForumComment).where(ForumComment.id == comment_id)
+    )
+    comment = result.scalar_one_or_none()
+    if not comment:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Comment not found"
+        )
+
+    comment.upvotes += 1
+    await db.commit()
+    await db.refresh(comment, ["author"])
+    return comment

app/routes/progress.py

@@ -0,0 +1,508 @@
+"""Student progress and enrollment routes."""
+
+from typing import List
+from datetime import datetime, date, timedelta
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func
+from sqlalchemy.orm import selectinload
+from app.database import get_db
+from app.models.user import User
+from app.models.course import Course, Module, Lesson
+from app.models.progress import Enrollment, Progress, StudyStreak
+from app.models.quiz import QuizAttempt
+from app.schemas.progress import (
+    EnrollmentCreate,
+    EnrollmentResponse,
+    ProgressUpdate,
+    ProgressResponse,
+    StudyStreakResponse,
+    DashboardStats,
+    CourseProgress,
+)
+from app.dependencies import get_current_user
+
+
+router = APIRouter(prefix="/progress", tags=["Progress"])
+
+
+@router.get("/dashboard", response_model=DashboardStats)
+async def get_dashboard_stats(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get student dashboard statistics."""
+    try:
+        # Get enrollments
+        enrollment_result = await db.execute(
+            select(Enrollment).where(Enrollment.student_id == current_user.id)
+        )
+        enrollments = enrollment_result.scalars().all()
+
+        enrolled_count = len(enrollments)
+        completed_count = sum(1 for e in enrollments if e.is_completed)
+
+        # Get lessons completed
+        progress_result = await db.execute(
+            select(Progress).where(
+                Progress.student_id == current_user.id,
+                Progress.is_completed == True,
+            )
+        )
+        lessons_completed = len(progress_result.scalars().all())
+
+        # Get total study time
+        time_result = await db.execute(
+            select(func.sum(Progress.time_spent_seconds)).where(
+                Progress.student_id == current_user.id
+            )
+        )
+        total_seconds = time_result.scalar() or 0
+        total_hours = round(total_seconds / 3600, 1)
+
+        # Get streak
+        streak_result = await db.execute(
+            select(StudyStreak).where(StudyStreak.student_id == current_user.id)
+        )
+        streak = streak_result.scalar_one_or_none()
+
+        # Get average quiz score
+        quiz_result = await db.execute(
+            select(func.avg(QuizAttempt.score)).where(
+                QuizAttempt.student_id == current_user.id,
+                QuizAttempt.completed_at.isnot(None),
+            )
+        )
+        avg_score = quiz_result.scalar() or 0.0
+
+        return DashboardStats(
+            enrolled_courses=enrolled_count,
+            completed_courses=completed_count,
+            lessons_completed=lessons_completed,
+            total_study_time_hours=total_hours,
+            current_streak=streak.current_streak if streak else 0,
+            longest_streak=streak.longest_streak if streak else 0,
+            average_quiz_score=round(avg_score, 1),
+        )
+    except Exception as e:
+        print(f"⚠️  Could not fetch dashboard stats: {e}")
+        return DashboardStats(
+            enrolled_courses=0,
+            completed_courses=0,
+            lessons_completed=0,
+            total_study_time_hours=0.0,
+            current_streak=0,
+            longest_streak=0,
+            average_quiz_score=0.0,
+        )
+
+
+@router.get("/enrollments", response_model=List[CourseProgress])
+async def get_enrollments(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get all enrollments for current user - alias for get_course_progress."""
+    try:
+        result = await db.execute(
+            select(Enrollment)
+            .options(selectinload(Enrollment.course).selectinload(Course.modules).selectinload(Module.lessons))
+            .where(Enrollment.student_id == current_user.id)
+        )
+        enrollments = result.scalars().all()
+
+        progress_list = []
+        for enrollment in enrollments:
+            course = enrollment.course
+            total_lessons = sum(len(m.lessons) for m in course.modules)
+
+            # Get completed lessons count
+            lesson_ids = [l.id for m in course.modules for l in m.lessons]
+            if lesson_ids:
+                completed_result = await db.execute(
+                    select(func.count(Progress.id)).where(
+                        Progress.student_id == current_user.id,
+                        Progress.lesson_id.in_(lesson_ids),
+                        Progress.is_completed == True,
+                    )
+                )
+                completed_count = completed_result.scalar() or 0
+            else:
+                completed_count = 0
+
+            # Calculate progress percentage from actual completed count
+            calculated_percentage = (completed_count / total_lessons * 100) if total_lessons > 0 else 0
+
+            progress_list.append(
+                CourseProgress(
+                    course_id=course.id,
+                    course_title=course.title,
+                    progress_percentage=calculated_percentage,
+                    lessons_completed=completed_count,
+                    total_lessons=total_lessons,
+                    last_accessed=enrollment.enrolled_at,
+                )
+            )
+
+        return progress_list
+    except Exception as e:
+        # In demo mode, return empty list
+        print(f"⚠️  Could not fetch enrollments: {e}")
+        return []
+
+
+@router.get("/courses", response_model=List[CourseProgress])
+async def get_course_progress(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get progress for all enrolled courses."""
+    try:
+        result = await db.execute(
+            select(Enrollment)
+            .options(selectinload(Enrollment.course).selectinload(Course.modules).selectinload(Module.lessons))
+            .where(Enrollment.student_id == current_user.id)
+        )
+        enrollments = result.scalars().all()
+
+        progress_list = []
+        for enrollment in enrollments:
+            course = enrollment.course
+            total_lessons = sum(len(m.lessons) for m in course.modules)
+
+            # Get completed lessons count
+            lesson_ids = [l.id for m in course.modules for l in m.lessons]
+            completed_result = await db.execute(
+                select(func.count(Progress.id)).where(
+                    Progress.student_id == current_user.id,
+                    Progress.lesson_id.in_(lesson_ids),
+                    Progress.is_completed == True,
+                )
+            )
+            completed_count = completed_result.scalar() or 0
+
+            # Calculate progress percentage from actual completed count
+            calculated_percentage = (completed_count / total_lessons * 100) if total_lessons > 0 else 0
+
+            progress_list.append(
+                CourseProgress(
+                    course_id=course.id,
+                    course_title=course.title,
+                    progress_percentage=calculated_percentage,
+                    lessons_completed=completed_count,
+                    total_lessons=total_lessons,
+                    last_accessed=enrollment.enrolled_at,
+                )
+            )
+
+        return progress_list
+    except Exception as e:
+        print(f"⚠️  Could not fetch course progress: {e}")
+        return []
+
+
+@router.post("/enroll", response_model=EnrollmentResponse, status_code=status.HTTP_201_CREATED)
+async def enroll_in_course(
+    data: EnrollmentCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Enroll in a course."""
+    # Check if course exists
+    course_result = await db.execute(select(Course).where(Course.id == data.course_id))
+    course = course_result.scalar_one_or_none()
+    if not course:
+        raise HTTPException(status_code=404, detail="Course not found")
+
+    # Prevent instructors from enrolling in their own courses
+    if course.created_by == current_user.id:
+        raise HTTPException(
+            status_code=400, 
+            detail="You cannot enroll in your own course. As the instructor, you have full access to manage it."
+        )
+
+    # Check if already enrolled
+    existing = await db.execute(
+        select(Enrollment).where(
+            Enrollment.student_id == current_user.id,
+            Enrollment.course_id == data.course_id,
+        )
+    )
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=400, detail="Already enrolled")
+
+    enrollment = Enrollment(
+        student_id=current_user.id,
+        course_id=data.course_id,
+    )
+    db.add(enrollment)
+    await db.commit()
+    await db.refresh(enrollment)
+
+    return EnrollmentResponse.model_validate(enrollment)
+
+
+@router.get("/lessons/{lesson_id}", response_model=ProgressResponse)
+async def get_lesson_progress(
+    lesson_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get progress for a specific lesson."""
+    lesson_result = await db.execute(select(Lesson).where(Lesson.id == lesson_id))
+    if not lesson_result.scalar_one_or_none():
+        raise HTTPException(status_code=404, detail="Lesson not found")
+
+    result = await db.execute(
+        select(Progress).where(
+            Progress.student_id == current_user.id,
+            Progress.lesson_id == lesson_id,
+        )
+    )
+    progress = result.scalar_one_or_none()
+
+    if not progress:
+        raise HTTPException(status_code=404, detail="Progress not found")
+
+    return ProgressResponse.model_validate(progress)
+
+
+@router.post("/lessons/{lesson_id}", response_model=ProgressResponse)
+async def update_lesson_progress(
+    lesson_id: str,
+    data: ProgressUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update progress for a lesson."""
+    # Check if lesson exists
+    lesson_result = await db.execute(select(Lesson).where(Lesson.id == lesson_id))
+    if not lesson_result.scalar_one_or_none():
+        raise HTTPException(status_code=404, detail="Lesson not found")
+
+    # Get or create progress record
+    result = await db.execute(
+        select(Progress).where(
+            Progress.student_id == current_user.id,
+            Progress.lesson_id == lesson_id,
+        )
+    )
+    progress = result.scalar_one_or_none()
+
+    if not progress:
+        progress = Progress(student_id=current_user.id, lesson_id=lesson_id)
+        db.add(progress)
+
+    # Update fields
+    for field, value in data.model_dump(exclude_unset=True).items():
+        setattr(progress, field, value)
+
+    if data.is_completed and not progress.completed_at:
+        progress.completed_at = datetime.utcnow()
+
+    await db.commit()
+    await db.refresh(progress)
+
+    # Update study streak
+    await _update_study_streak(current_user.id, db)
+
+    return ProgressResponse.model_validate(progress)
+
+
+@router.post("/lesson/{lesson_id}/complete")
+async def mark_lesson_complete(
+    lesson_id: str,
+    data: ProgressUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Mark a lesson as complete."""
+    # Check if lesson exists
+    lesson_result = await db.execute(select(Lesson).where(Lesson.id == lesson_id))
+    lesson = lesson_result.scalar_one_or_none()
+    if not lesson:
+        raise HTTPException(status_code=404, detail="Lesson not found")
+
+    # Get or create progress record
+    result = await db.execute(
+        select(Progress).where(
+            Progress.student_id == current_user.id,
+            Progress.lesson_id == lesson_id,
+        )
+    )
+    progress = result.scalar_one_or_none()
+
+    if not progress:
+        progress = Progress(student_id=current_user.id, lesson_id=lesson_id)
+        db.add(progress)
+
+    # Mark as completed
+    progress.is_completed = True
+    if not progress.completed_at:
+        progress.completed_at = datetime.utcnow()
+
+    # Update time spent if provided
+    if data.time_spent_seconds:
+        progress.time_spent_seconds = data.time_spent_seconds
+
+    await db.commit()
+    await db.refresh(progress)
+
+    # Update enrollment progress percentage
+    # Get the course for this lesson
+    module_result = await db.execute(
+        select(Module).options(selectinload(Module.course)).where(Module.id == lesson.module_id)
+    )
+    module = module_result.scalar_one_or_none()
+    
+    if module and module.course:
+        course = module.course
+        # Get total lessons in course
+        total_lessons_result = await db.execute(
+            select(func.count(Lesson.id)).where(
+                Lesson.module_id.in_(
+                    select(Module.id).where(Module.course_id == course.id)
+                )
+            )
+        )
+        total_lessons = total_lessons_result.scalar() or 0
+        
+        if total_lessons > 0:
+            # Get completed lessons count
+            completed_result = await db.execute(
+                select(func.count(Progress.id)).where(
+                    Progress.student_id == current_user.id,
+                    Progress.lesson_id.in_(
+                        select(Lesson.id).where(
+                            Lesson.module_id.in_(
+                                select(Module.id).where(Module.course_id == course.id)
+                            )
+                        )
+                    ),
+                    Progress.is_completed == True,
+                )
+            )
+            completed_count = completed_result.scalar() or 0
+            progress_percentage = (completed_count / total_lessons) * 100 if total_lessons > 0 else 0
+            
+            # Update enrollment progress
+            enrollment_result = await db.execute(
+                select(Enrollment).where(
+                    Enrollment.student_id == current_user.id,
+                    Enrollment.course_id == course.id,
+                )
+            )
+            enrollment = enrollment_result.scalar_one_or_none()
+            if enrollment:
+                enrollment.progress_percentage = progress_percentage
+                await db.commit()
+                await db.refresh(enrollment)
+
+    # Update study streak
+    await _update_study_streak(current_user.id, db)
+
+    return ProgressResponse.model_validate(progress)
+
+
+@router.get("/streak", response_model=StudyStreakResponse)
+async def get_study_streak(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get current study streak."""
+    try:
+        result = await db.execute(
+            select(StudyStreak).where(StudyStreak.student_id == current_user.id)
+        )
+        streak = result.scalar_one_or_none()
+
+        if not streak:
+            return StudyStreakResponse(
+                current_streak=0,
+                longest_streak=0,
+                last_study_date=None,
+                total_study_days=0,
+            )
+
+        return StudyStreakResponse.model_validate(streak)
+    except Exception as e:
+        # In demo mode, return default values
+        print(f"⚠️  Could not fetch study streak: {e}")
+        return StudyStreakResponse(
+            current_streak=0,
+            longest_streak=0,
+            last_study_date=None,
+            total_study_days=0,
+        )
+
+
+@router.post("/study", response_model=StudyStreakResponse)
+async def record_study_session(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Record a study session and update study streak."""
+    try:
+        await _update_study_streak(current_user.id, db)
+        
+        result = await db.execute(
+            select(StudyStreak).where(StudyStreak.student_id == current_user.id)
+        )
+        streak = result.scalar_one_or_none()
+        
+        if not streak:
+            return StudyStreakResponse(
+                current_streak=0,
+                longest_streak=0,
+                last_study_date=None,
+                total_study_days=0,
+            )
+        
+        return StudyStreakResponse.model_validate(streak)
+    except Exception as e:
+        print(f"⚠️  Could not record study session: {e}")
+        return StudyStreakResponse(
+            current_streak=0,
+            longest_streak=0,
+            last_study_date=None,
+            total_study_days=0,
+        )
+
+
+async def _update_study_streak(user_id: str, db: AsyncSession):
+    """Update study streak for a user."""
+    result = await db.execute(
+        select(StudyStreak).where(StudyStreak.student_id == user_id)
+    )
+    streak = result.scalar_one_or_none()
+
+    today = date.today()
+
+    if not streak:
+        streak = StudyStreak(
+            student_id=user_id,
+            current_streak=1,
+            longest_streak=1,
+            last_study_date=datetime.utcnow(),
+            total_study_days=1,
+        )
+        db.add(streak)
+    else:
+        last_date = streak.last_study_date.date() if streak.last_study_date else None
+
+        if last_date == today:
+            # Already studied today
+            pass
+        elif last_date == today - timedelta(days=1):
+            # Consecutive day
+            streak.current_streak += 1
+            streak.longest_streak = max(streak.longest_streak, streak.current_streak)
+            streak.total_study_days += 1
+            streak.last_study_date = datetime.utcnow()
+        else:
+            # Streak broken
+            streak.current_streak = 1
+            streak.total_study_days += 1
+            streak.last_study_date = datetime.utcnow()
+
+    await db.commit()

app/routes/quiz.py

@@ -0,0 +1,582 @@
+"""Quiz management and assessment routes."""
+
+import re
+from typing import List, Optional
+from datetime import datetime
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, and_, func
+from sqlalchemy.orm import selectinload
+from app.database import get_db
+from app.models.user import User, UserRole
+from app.models.quiz import Quiz, QuizQuestion, QuizAttempt, QuestionType
+from app.models.course import Lesson
+from app.dependencies import get_current_user, require_instructor
+from pydantic import BaseModel, Field
+
+
+router = APIRouter(prefix="/quizzes", tags=["Quizzes"])
+
+
+# ─── Schemas ─────────────────────────────────────────────
+
+class QuestionCreate(BaseModel):
+    question_type: QuestionType = QuestionType.MULTIPLE_CHOICE
+    question_text: str
+    options: Optional[List[str]] = None
+    correct_answer: str
+    explanation: Optional[str] = None
+    points: int = 1
+    order_index: int = 0
+
+
+class QuestionResponse(BaseModel):
+    id: str
+    question_type: str
+    question_text: str
+    options: Optional[List[str]] = None
+    correct_answer: str
+    explanation: Optional[str] = None
+    points: int
+    order_index: int
+
+    class Config:
+        from_attributes = True
+
+
+class QuizCreate(BaseModel):
+    lesson_id: str
+    title: str
+    description: Optional[str] = None
+    passing_score: float = 70.0
+    time_limit_minutes: Optional[int] = None
+    max_attempts: int = 3
+    is_ai_generated: bool = False
+    is_published: bool = False
+    questions: List[QuestionCreate] = []
+
+
+class QuizUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    passing_score: Optional[float] = None
+    time_limit_minutes: Optional[int] = None
+    max_attempts: Optional[int] = None
+    is_published: Optional[bool] = None
+
+
+class QuizResponse(BaseModel):
+    id: str
+    lesson_id: str
+    title: str
+    description: Optional[str] = None
+    passing_score: float
+    time_limit_minutes: Optional[int] = None
+    max_attempts: int
+    is_ai_generated: bool
+    is_published: bool
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class QuizWithQuestions(QuizResponse):
+    questions: List[QuestionResponse] = []
+
+
+class QuizQuestionPublic(BaseModel):
+    """Quiz question without correct answer (for students taking quiz)."""
+    id: str
+    question_type: str
+    question_text: str
+    options: Optional[List[str]] = None
+    points: int
+    order_index: int
+
+    class Config:
+        from_attributes = True
+
+
+class QuizForStudent(QuizResponse):
+    """Quiz with questions but without correct answers."""
+    questions: List[QuizQuestionPublic] = []
+    attempts_left: int = 0
+
+
+class AnswerSubmission(BaseModel):
+    question_id: str
+    answer: str
+
+
+class QuizSubmission(BaseModel):
+    quiz_id: str
+    answers: List[AnswerSubmission]
+    time_taken_seconds: Optional[int] = None
+
+
+class AttemptResponse(BaseModel):
+    id: str
+    quiz_id: str
+    student_id: str
+    score: float
+    passed: bool
+    answers: Optional[dict] = None
+    time_taken_seconds: Optional[int] = None
+    started_at: datetime
+    completed_at: Optional[datetime] = None
+
+    class Config:
+        from_attributes = True
+
+
+class AttemptWithQuiz(AttemptResponse):
+    quiz: QuizResponse
+
+
+class QuestionResult(BaseModel):
+    question_id: str
+    question_text: str
+    student_answer: str
+    correct_answer: str
+    is_correct: bool
+    points_earned: int
+    points_possible: int
+    explanation: Optional[str] = None
+
+
+class DetailedAttemptResponse(AttemptResponse):
+    quiz: QuizResponse
+    question_results: List[QuestionResult] = []
+
+
+# ─── Quiz CRUD (Instructor) ──────────────────────────────
+
+@router.post("", response_model=QuizResponse, status_code=status.HTTP_201_CREATED)
+async def create_quiz(
+    data: QuizCreate,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Create a new quiz (instructor only)."""
+    # Verify lesson exists
+    lesson_result = await db.execute(
+        select(Lesson).where(Lesson.id == data.lesson_id)
+    )
+    lesson = lesson_result.scalar_one_or_none()
+    if not lesson:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Lesson not found"
+        )
+
+    # Create quiz
+    quiz = Quiz(
+        lesson_id=data.lesson_id,
+        title=data.title,
+        description=data.description,
+        passing_score=data.passing_score,
+        time_limit_minutes=data.time_limit_minutes,
+        max_attempts=data.max_attempts,
+        is_ai_generated=data.is_ai_generated,
+        is_published=data.is_published,
+    )
+    db.add(quiz)
+    await db.flush()
+
+    # Create questions
+    for q_data in data.questions:
+        question = QuizQuestion(
+            quiz_id=quiz.id,
+            question_type=q_data.question_type,
+            question_text=q_data.question_text,
+            options=q_data.options,
+            correct_answer=q_data.correct_answer,
+            explanation=q_data.explanation,
+            points=q_data.points,
+            order_index=q_data.order_index,
+        )
+        db.add(question)
+
+    await db.commit()
+    await db.refresh(quiz)
+    return quiz
+
+
+@router.get("/lesson/{lesson_id}", response_model=List[QuizResponse])
+async def get_lesson_quizzes(
+    lesson_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get all quizzes for a lesson."""
+    query = select(Quiz).where(Quiz.lesson_id == lesson_id)
+    
+    # Students only see published quizzes
+    if current_user.role == UserRole.STUDENT:
+        query = query.where(Quiz.is_published == True)
+    
+    result = await db.execute(query.order_by(Quiz.created_at))
+    quizzes = result.scalars().all()
+    return quizzes
+
+
+@router.get("/{quiz_id}", response_model=QuizWithQuestions)
+async def get_quiz(
+    quiz_id: str,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get quiz details with questions (instructor only)."""
+    result = await db.execute(
+        select(Quiz)
+        .options(selectinload(Quiz.questions))
+        .where(Quiz.id == quiz_id)
+    )
+    quiz = result.scalar_one_or_none()
+    if not quiz:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Quiz not found"
+        )
+    return quiz
+
+
+@router.get("/{quiz_id}/take", response_model=QuizForStudent)
+async def get_quiz_for_taking(
+    quiz_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get quiz for student to take (without correct answers)."""
+    result = await db.execute(
+        select(Quiz)
+        .options(selectinload(Quiz.questions))
+        .where(Quiz.id == quiz_id)
+    )
+    quiz = result.scalar_one_or_none()
+    if not quiz:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Quiz not found"
+        )
+
+    if not quiz.is_published and current_user.role == UserRole.STUDENT:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Quiz is not published"
+        )
+
+    # Check attempts left (only for students)
+    attempts_left = quiz.max_attempts  # Default for instructors
+    if current_user.role == UserRole.STUDENT:
+        attempts_result = await db.execute(
+            select(func.count(QuizAttempt.id))
+            .where(
+                and_(
+                    QuizAttempt.quiz_id == quiz_id,
+                    QuizAttempt.student_id == current_user.id,
+                    QuizAttempt.completed_at.isnot(None)
+                )
+            )
+        )
+        attempts_count = attempts_result.scalar() or 0
+        attempts_left = max(0, quiz.max_attempts - attempts_count)
+
+    # Return quiz without correct answers
+    quiz_dict = {
+        "id": quiz.id,
+        "lesson_id": quiz.lesson_id,
+        "title": quiz.title,
+        "description": quiz.description,
+        "passing_score": quiz.passing_score,
+        "time_limit_minutes": quiz.time_limit_minutes,
+        "max_attempts": quiz.max_attempts,
+        "is_ai_generated": quiz.is_ai_generated,
+        "is_published": quiz.is_published,
+        "created_at": quiz.created_at,
+        "updated_at": quiz.updated_at,
+        "questions": [
+            {
+                "id": q.id,
+                "question_type": q.question_type,
+                "question_text": q.question_text,
+                "options": q.options,
+                "points": q.points,
+                "order_index": q.order_index,
+            }
+            for q in sorted(quiz.questions, key=lambda x: x.order_index)
+        ],
+        "attempts_left": attempts_left,
+    }
+    return quiz_dict
+
+
+@router.put("/{quiz_id}", response_model=QuizResponse)
+async def update_quiz(
+    quiz_id: str,
+    data: QuizUpdate,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update quiz (instructor only)."""
+    result = await db.execute(select(Quiz).where(Quiz.id == quiz_id))
+    quiz = result.scalar_one_or_none()
+    if not quiz:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Quiz not found"
+        )
+
+    # Update fields
+    for field, value in data.model_dump(exclude_unset=True).items():
+        setattr(quiz, field, value)
+
+    await db.commit()
+    await db.refresh(quiz)
+    return quiz
+
+
+@router.delete("/{quiz_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_quiz(
+    quiz_id: str,
+    current_user: User = Depends(require_instructor),
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete quiz (instructor only)."""
+    result = await db.execute(select(Quiz).where(Quiz.id == quiz_id))
+    quiz = result.scalar_one_or_none()
+    if not quiz:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Quiz not found"
+        )
+
+    await db.delete(quiz)
+    await db.commit()
+
+
+# ─── Quiz Attempts (Student) ─────────────────────────────
+
+@router.post("/submit", response_model=DetailedAttemptResponse)
+async def submit_quiz(
+    submission: QuizSubmission,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Submit quiz answers and get graded results."""
+    # Get quiz with questions
+    result = await db.execute(
+        select(Quiz)
+        .options(selectinload(Quiz.questions))
+        .where(Quiz.id == submission.quiz_id)
+    )
+    quiz = result.scalar_one_or_none()
+    if not quiz:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Quiz not found"
+        )
+
+    # Check if quiz is published
+    if not quiz.is_published and current_user.role == UserRole.STUDENT:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Quiz is not published"
+        )
+
+    # Check max attempts (only for students)
+    if current_user.role == UserRole.STUDENT:
+        attempts_result = await db.execute(
+            select(func.count(QuizAttempt.id))
+            .where(
+                and_(
+                    QuizAttempt.quiz_id == submission.quiz_id,
+                    QuizAttempt.student_id == current_user.id,
+                    QuizAttempt.completed_at.isnot(None)
+                )
+            )
+        )
+        attempts_count = attempts_result.scalar() or 0
+        if attempts_count >= quiz.max_attempts:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Maximum attempts reached"
+            )
+
+    # Grade the quiz
+    total_points = 0
+    earned_points = 0
+    question_results = []
+    answers_dict = {}
+
+    for q in quiz.questions:
+        total_points += q.points
+        
+        # Find student's answer
+        student_answer = next(
+            (a.answer for a in submission.answers if a.question_id == q.id),
+            None
+        )
+        
+        if student_answer is None:
+            student_answer = ""
+        
+        # Strip "A. " prefixes from both answers for comparison
+        clean_student_answer = re.sub(r'^[A-D]\.\s*', '', student_answer.strip())
+        clean_correct_answer = re.sub(r'^[A-D]\.\s*', '', q.correct_answer.strip())
+        
+        # Check if correct (case-insensitive, prefix-stripped comparison)
+        is_correct = clean_student_answer.lower() == clean_correct_answer.lower()
+        points_earned = q.points if is_correct else 0
+        earned_points += points_earned
+
+        question_results.append({
+            "question_id": q.id,
+            "question_text": q.question_text,
+            "student_answer": student_answer,
+            "correct_answer": q.correct_answer,
+            "is_correct": is_correct,
+            "points_earned": points_earned,
+            "points_possible": q.points,
+            "explanation": q.explanation,
+        })
+
+        answers_dict[q.id] = {
+            "answer": student_answer,
+            "correct": is_correct,
+            "points": points_earned,
+        }
+
+    # Calculate score percentage
+    score = (earned_points / total_points * 100) if total_points > 0 else 0
+    passed = score >= quiz.passing_score
+
+    # Save attempt
+    attempt = QuizAttempt(
+        quiz_id=submission.quiz_id,
+        student_id=current_user.id,
+        score=round(score, 2),
+        passed=passed,
+        answers=answers_dict,
+        time_taken_seconds=submission.time_taken_seconds,
+        completed_at=datetime.utcnow(),
+    )
+    db.add(attempt)
+    await db.commit()
+    await db.refresh(attempt)
+
+    # Return detailed results
+    return {
+        "id": attempt.id,
+        "quiz_id": attempt.quiz_id,
+        "student_id": attempt.student_id,
+        "score": attempt.score,
+        "passed": attempt.passed,
+        "answers": attempt.answers,
+        "time_taken_seconds": attempt.time_taken_seconds,
+        "started_at": attempt.started_at,
+        "completed_at": attempt.completed_at,
+        "quiz": quiz,
+        "question_results": question_results,
+    }
+
+
+@router.get("/attempts/my", response_model=List[AttemptWithQuiz])
+async def get_my_attempts(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get all quiz attempts for current user."""
+    result = await db.execute(
+        select(QuizAttempt)
+        .options(selectinload(QuizAttempt.quiz))
+        .where(QuizAttempt.student_id == current_user.id)
+        .where(QuizAttempt.completed_at.isnot(None))
+        .order_by(QuizAttempt.completed_at.desc())
+    )
+    attempts = result.scalars().all()
+    return attempts
+
+
+@router.get("/attempts/{attempt_id}", response_model=DetailedAttemptResponse)
+async def get_attempt_details(
+    attempt_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get detailed results for a specific attempt."""
+    result = await db.execute(
+        select(QuizAttempt)
+        .options(
+            selectinload(QuizAttempt.quiz).selectinload(Quiz.questions)
+        )
+        .where(QuizAttempt.id == attempt_id)
+    )
+    attempt = result.scalar_one_or_none()
+    if not attempt:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Attempt not found"
+        )
+
+    # Check permissions
+    if attempt.student_id != current_user.id and current_user.role != UserRole.INSTRUCTOR:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Not authorized to view this attempt"
+        )
+
+    # Reconstruct question results
+    question_results = []
+    for q in attempt.quiz.questions:
+        answer_data = attempt.answers.get(q.id, {})
+        question_results.append({
+            "question_id": q.id,
+            "question_text": q.question_text,
+            "student_answer": answer_data.get("answer", ""),
+            "correct_answer": q.correct_answer,
+            "is_correct": answer_data.get("correct", False),
+            "points_earned": answer_data.get("points", 0),
+            "points_possible": q.points,
+            "explanation": q.explanation,
+        })
+
+    return {
+        "id": attempt.id,
+        "quiz_id": attempt.quiz_id,
+        "student_id": attempt.student_id,
+        "score": attempt.score,
+        "passed": attempt.passed,
+        "answers": attempt.answers,
+        "time_taken_seconds": attempt.time_taken_seconds,
+        "started_at": attempt.started_at,
+        "completed_at": attempt.completed_at,
+        "quiz": attempt.quiz,
+        "question_results": question_results,
+    }
+
+
+@router.get("/lesson/{lesson_id}/attempts", response_model=List[AttemptWithQuiz])
+async def get_lesson_attempts(
+    lesson_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get all attempts for quizzes in a lesson (for current user)."""
+    result = await db.execute(
+        select(QuizAttempt)
+        .join(Quiz)
+        .options(selectinload(QuizAttempt.quiz))
+        .where(
+            and_(
+                Quiz.lesson_id == lesson_id,
+                QuizAttempt.student_id == current_user.id,
+                QuizAttempt.completed_at.isnot(None)
+            )
+        )
+        .order_by(QuizAttempt.completed_at.desc())
+    )
+    attempts = result.scalars().all()
+    return attempts

app/routes/tutor.py

@@ -0,0 +1,193 @@
+"""AI Tutor routes for enhanced learning features."""
+
+import os
+from pypdf import PdfReader
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from app.database import get_db
+from app.models.user import User
+from app.models.course import Lesson, ContentType
+from app.config import settings
+from app.schemas.tutor import (
+    AskTutorRequest,
+    AskTutorResponse,
+    GenerateSummaryRequest,
+    SummaryResponse,
+    GenerateMCQRequest,
+    GenerateMCQResponse,
+    HintRequest,
+    HintResponse,
+    SourceDocument,
+)
+from app.services.tutor import tutor_service
+from app.dependencies import get_current_user
+
+
+router = APIRouter(prefix="/tutor", tags=["AI Tutor"])
+
+
+def extract_pdf_text(file_path: str, max_pages: int = 10) -> str:
+    """Extract text from PDF file (limit to first N pages for performance)."""
+    try:
+        reader = PdfReader(file_path)
+        text_parts = []
+        
+        # Limit pages to prevent huge content
+        num_pages = min(len(reader.pages), max_pages)
+        
+        for i in range(num_pages):
+            page = reader.pages[i]
+            text = page.extract_text()
+            if text:
+                text_parts.append(text)
+        
+        extracted_text = "\n\n".join(text_parts)
+        
+        # Limit total length (gemini has token limits)
+        if len(extracted_text) > 15000:
+            extracted_text = extracted_text[:15000] + "\n\n[Content truncated for length...]"
+        
+        return extracted_text
+    except Exception as e:
+        print(f"⚠️  PDF extraction error: {e}")
+        return ""
+
+
+def get_lesson_content(lesson: Lesson) -> str:
+    """Get content from lesson based on content type."""
+    # For markdown, use content_text
+    if lesson.content_type == ContentType.MARKDOWN:
+        return lesson.content_text or f"Lesson: {lesson.title}\n{lesson.description or ''}"
+    
+    # For PDF, extract text from file
+    if lesson.content_type == ContentType.PDF and lesson.content_url:
+        file_path = os.path.join(settings.UPLOAD_DIR, os.path.basename(lesson.content_url))
+        if os.path.exists(file_path):
+            pdf_text = extract_pdf_text(file_path, max_pages=10)
+            if pdf_text:
+                return f"Lesson: {lesson.title}\n\n{pdf_text}"
+    
+    # Fallback to title + description
+    return f"Lesson: {lesson.title}\n{lesson.description or 'No content available.'}"
+
+
+@router.post("/ask", response_model=AskTutorResponse)
+async def ask_tutor(
+    data: AskTutorRequest,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Ask the AI tutor a question with optional lesson/module context."""
+    try:
+        answer, sources = await tutor_service.ask_question(
+            question=data.question,
+            lesson_context=data.lesson_id,
+            module_context=data.module_id,
+        )
+
+        return AskTutorResponse(
+            answer=answer,
+            conversation_id=data.conversation_id or "new",
+            sources=sources,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/summary", response_model=SummaryResponse)
+async def generate_summary(
+    data: GenerateSummaryRequest,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Generate a summary for a lesson."""
+    try:
+        result = await db.execute(select(Lesson).where(Lesson.id == data.lesson_id))
+        lesson = result.scalar_one_or_none()
+    except Exception as e:
+        print(f"⚠️  Could not fetch lesson for summary: {e}")
+        lesson = None
+
+    if not lesson:
+        raise HTTPException(status_code=404, detail="Lesson not found")
+
+    # Get content based on lesson type (handles PDF extraction)
+    content = get_lesson_content(lesson)
+
+    try:
+        summary, key_points = await tutor_service.generate_summary(
+            content=content,
+            title=lesson.title,
+        )
+
+        return SummaryResponse(
+            lesson_id=data.lesson_id,
+            summary=summary,
+            key_points=key_points,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/mcq", response_model=GenerateMCQResponse)
+async def generate_mcq(
+    data: GenerateMCQRequest,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Generate MCQ questions for a lesson."""
+    try:
+        result = await db.execute(select(Lesson).where(Lesson.id == data.lesson_id))
+        lesson = result.scalar_one_or_none()
+    except Exception as e:
+        print(f"⚠️  Could not fetch lesson for MCQ: {e}")
+        lesson = None
+
+    if not lesson:
+        raise HTTPException(status_code=404, detail="Lesson not found")
+
+    # Get content based on lesson type (handles PDF extraction)
+    content = get_lesson_content(lesson)
+    
+    if not content or len(content) < 100:
+        raise HTTPException(
+            status_code=400, 
+            detail="Insufficient content to generate quiz. Please add more content to the lesson."
+        )
+
+    try:
+        questions = await tutor_service.generate_mcqs(
+            content=content,
+            num_questions=data.num_questions,
+            difficulty=data.difficulty,
+        )
+
+        return GenerateMCQResponse(
+            lesson_id=data.lesson_id,
+            questions=questions,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/hint", response_model=HintResponse)
+async def get_hint(
+    data: HintRequest,
+    current_user: User = Depends(get_current_user),
+):
+    """Get a progressive hint for a question."""
+    try:
+        hint, has_more = await tutor_service.generate_hint(
+            question=data.question,
+            context=data.context,
+            hint_level=data.hint_level,
+        )
+
+        return HintResponse(
+            hint=hint,
+            hint_level=data.hint_level,
+            has_more_hints=has_more,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

app/schemas/course.py

@@ -0,0 +1,154 @@
+"""Course and module schemas."""
+
+from pydantic import BaseModel, Field
+from typing import Optional, List
+from datetime import datetime
+from app.models.course import ContentType, DifficultyLevel
+
+
+# ─── Course ──────────────────────────────────────────────
+
+class CourseCreate(BaseModel):
+    title: str = Field(..., min_length=1, max_length=255)
+    slug: str = Field(..., min_length=1, max_length=255)
+    description: Optional[str] = None
+    thumbnail_url: Optional[str] = None
+    difficulty: DifficultyLevel = DifficultyLevel.BEGINNER
+    estimated_hours: int = 0
+
+
+class CourseUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    thumbnail_url: Optional[str] = None
+    difficulty: Optional[DifficultyLevel] = None
+    estimated_hours: Optional[int] = None
+    is_published: Optional[bool] = None
+    is_featured: Optional[bool] = None
+    order_index: Optional[int] = None
+
+
+class CourseResponse(BaseModel):
+    id: str
+    title: str
+    slug: str
+    description: Optional[str]
+    thumbnail_url: Optional[str]
+    difficulty: DifficultyLevel
+    is_published: bool
+    is_featured: bool
+    estimated_hours: int
+    order_index: int
+    created_by: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+    module_count: int = 0
+    enrolled_count: int = 0
+
+    class Config:
+        from_attributes = True
+
+
+class CourseBrief(BaseModel):
+    id: str
+    title: str
+    slug: str
+    thumbnail_url: Optional[str]
+    difficulty: DifficultyLevel
+    estimated_hours: int
+
+    class Config:
+        from_attributes = True
+
+
+# ─── Module ──────────────────────────────────────────────
+
+class ModuleCreate(BaseModel):
+    title: str = Field(..., min_length=1, max_length=255)
+    description: Optional[str] = None
+    order_index: int = 0
+    prerequisite_module_id: Optional[str] = None
+
+
+class ModuleUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    order_index: Optional[int] = None
+    is_published: Optional[bool] = None
+    prerequisite_module_id: Optional[str] = None
+
+
+class ModuleResponse(BaseModel):
+    id: str
+    course_id: str
+    title: str
+    description: Optional[str]
+    order_index: int
+    is_published: bool
+    prerequisite_module_id: Optional[str]
+    created_at: datetime
+    lesson_count: int = 0
+
+    class Config:
+        from_attributes = True
+
+
+# ─── Lesson ──────────────────────────────────────────────
+
+class LessonCreate(BaseModel):
+    title: str = Field(..., min_length=1, max_length=255)
+    description: Optional[str] = None
+    content_type: ContentType
+    content_url: Optional[str] = None
+    content_text: Optional[str] = None
+    duration_minutes: int = 0
+    order_index: int = 0
+
+
+class LessonUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    content_type: Optional[ContentType] = None
+    content_url: Optional[str] = None
+    content_text: Optional[str] = None
+    duration_minutes: Optional[int] = None
+    order_index: Optional[int] = None
+    is_published: Optional[bool] = None
+
+
+class LessonResponse(BaseModel):
+    id: str
+    module_id: str
+    title: str
+    description: Optional[str]
+    content_type: ContentType
+    content_url: Optional[str]
+    content_text: Optional[str]
+    duration_minutes: int
+    order_index: int
+    is_published: bool
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class LessonBrief(BaseModel):
+    id: str
+    title: str
+    content_type: ContentType
+    duration_minutes: int
+    order_index: int
+
+    class Config:
+        from_attributes = True
+
+
+# ─── Full Course with Modules ─────────────────────────────
+
+class ModuleWithLessons(ModuleResponse):
+    lessons: List[LessonBrief] = []
+
+
+class CourseWithModules(CourseResponse):
+    modules: List[ModuleWithLessons] = []

app/schemas/progress.py

@@ -0,0 +1,83 @@
+"""Progress and enrollment schemas."""
+
+from pydantic import BaseModel
+from typing import Optional
+from datetime import datetime
+
+
+class EnrollmentCreate(BaseModel):
+    course_id: str
+
+
+class EnrollmentResponse(BaseModel):
+    id: str
+    student_id: str
+    course_id: str
+    enrolled_at: datetime
+    completed_at: Optional[datetime]
+    is_completed: bool
+    progress_percentage: float
+
+    class Config:
+        from_attributes = True
+
+
+class EnrollmentWithStudent(BaseModel):
+    id: str
+    student_id: str
+    student_name: str
+    student_email: str
+    course_id: str
+    enrolled_at: datetime
+    completed_at: Optional[datetime]
+    is_completed: bool
+    progress_percentage: float
+
+
+class ProgressUpdate(BaseModel):
+    is_completed: Optional[bool] = None
+    time_spent_seconds: Optional[int] = None
+    last_position: Optional[int] = None
+
+
+class ProgressResponse(BaseModel):
+    id: str
+    student_id: str
+    lesson_id: str
+    is_completed: bool
+    completed_at: Optional[datetime]
+    time_spent_seconds: int
+    last_position: int
+    started_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class StudyStreakResponse(BaseModel):
+    current_streak: int
+    longest_streak: int
+    last_study_date: Optional[datetime]
+    total_study_days: int
+
+    class Config:
+        from_attributes = True
+
+
+class DashboardStats(BaseModel):
+    enrolled_courses: int
+    completed_courses: int
+    lessons_completed: int
+    total_study_time_hours: float
+    current_streak: int
+    longest_streak: int
+    average_quiz_score: float
+
+
+class CourseProgress(BaseModel):
+    course_id: str
+    course_title: str
+    progress_percentage: float
+    lessons_completed: int
+    total_lessons: int
+    last_accessed: Optional[datetime]

app/schemas/quiz.py

@@ -0,0 +1,114 @@
+"""Quiz schemas."""
+
+from pydantic import BaseModel, Field
+from typing import Optional, List, Any
+from datetime import datetime
+from app.models.quiz import QuestionType
+
+
+class QuizCreate(BaseModel):
+    title: str = Field(..., min_length=1, max_length=255)
+    description: Optional[str] = None
+    passing_score: float = 70.0
+    time_limit_minutes: Optional[int] = None
+    max_attempts: int = 3
+
+
+class QuizUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    passing_score: Optional[float] = None
+    time_limit_minutes: Optional[int] = None
+    max_attempts: Optional[int] = None
+    is_published: Optional[bool] = None
+
+
+class QuizResponse(BaseModel):
+    id: str
+    lesson_id: str
+    title: str
+    description: Optional[str]
+    passing_score: float
+    time_limit_minutes: Optional[int]
+    max_attempts: int
+    is_ai_generated: bool
+    is_published: bool
+    question_count: int = 0
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class QuestionCreate(BaseModel):
+    question_type: QuestionType = QuestionType.MULTIPLE_CHOICE
+    question_text: str
+    options: Optional[List[str]] = None
+    correct_answer: str
+    explanation: Optional[str] = None
+    points: int = 1
+    order_index: int = 0
+
+
+class QuestionResponse(BaseModel):
+    id: str
+    question_type: str
+    question_text: str
+    options: Optional[List[str]]
+    correct_answer: str
+    explanation: Optional[str]
+    points: int
+    order_index: int
+
+    class Config:
+        from_attributes = True
+
+
+class QuestionForStudent(BaseModel):
+    """Question without correct answer (for taking quiz)."""
+    id: str
+    question_type: str
+    question_text: str
+    options: Optional[List[str]]
+    points: int
+
+    class Config:
+        from_attributes = True
+
+
+class QuizWithQuestions(QuizResponse):
+    questions: List[QuestionForStudent] = []
+
+
+class AnswerSubmit(BaseModel):
+    question_id: str
+    answer: str
+
+
+class QuizSubmit(BaseModel):
+    answers: List[AnswerSubmit]
+
+
+class QuizAttemptResponse(BaseModel):
+    id: str
+    quiz_id: str
+    score: float
+    passed: bool
+    answers: Optional[dict]
+    time_taken_seconds: Optional[int]
+    started_at: datetime
+    completed_at: Optional[datetime]
+
+    class Config:
+        from_attributes = True
+
+
+class QuizResultDetail(BaseModel):
+    question_id: str
+    question_text: str
+    your_answer: str
+    correct_answer: str
+    is_correct: bool
+    explanation: Optional[str]
+    points_earned: int
+    points_possible: int

app/schemas/tutor.py

@@ -0,0 +1,63 @@
+"""AI Tutor schemas."""
+
+from pydantic import BaseModel, Field
+from typing import Optional, List
+
+
+class AskTutorRequest(BaseModel):
+    question: str = Field(..., min_length=1, max_length=2000)
+    lesson_id: Optional[str] = None  # Context from specific lesson
+    module_id: Optional[str] = None  # Context from specific module
+    conversation_id: Optional[str] = None
+
+
+class SourceDocument(BaseModel):
+    content: str
+    source: str
+    page: Optional[int] = None
+
+
+class AskTutorResponse(BaseModel):
+    answer: str
+    conversation_id: str
+    sources: List[SourceDocument] = []
+
+
+class GenerateSummaryRequest(BaseModel):
+    lesson_id: str
+
+
+class SummaryResponse(BaseModel):
+    lesson_id: str
+    summary: str
+    key_points: List[str]
+
+
+class GenerateMCQRequest(BaseModel):
+    lesson_id: str
+    num_questions: int = Field(default=5, ge=1, le=20)
+    difficulty: str = "medium"  # easy, medium, hard
+
+
+class GeneratedMCQ(BaseModel):
+    question: str
+    options: List[str]
+    correct_answer: str
+    explanation: str
+
+
+class GenerateMCQResponse(BaseModel):
+    lesson_id: str
+    questions: List[GeneratedMCQ]
+
+
+class HintRequest(BaseModel):
+    question: str
+    context: Optional[str] = None
+    hint_level: int = Field(default=1, ge=1, le=3)  # 1=subtle, 2=moderate, 3=strong
+
+
+class HintResponse(BaseModel):
+    hint: str
+    hint_level: int
+    has_more_hints: bool

app/schemas/user.py

@@ -0,0 +1,68 @@
+"""User schemas for API requests/responses."""
+
+from pydantic import BaseModel, EmailStr, Field, field_validator
+from typing import Optional, Literal
+from datetime import datetime
+from app.models.user import UserRole
+
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str = Field(..., min_length=8)
+    full_name: str = Field(..., min_length=2, max_length=255)
+    role: Optional[Literal["student", "instructor"]] = "student"  # Only student or instructor allowed
+    
+    @field_validator("role")
+    @classmethod
+    def validate_role(cls, v):
+        if v not in ["student", "instructor"]:
+            raise ValueError("Role must be either 'student' or 'instructor'")
+        return v
+
+
+class UserLogin(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class UserUpdate(BaseModel):
+    full_name: Optional[str] = None
+    avatar_url: Optional[str] = None
+    bio: Optional[str] = None
+
+
+class UserResponse(BaseModel):
+    id: str
+    email: str
+    full_name: str
+    avatar_url: Optional[str]
+    role: UserRole
+    is_active: bool
+    is_verified: bool
+    bio: Optional[str]
+    created_at: datetime
+    last_login: Optional[datetime]
+
+    class Config:
+        from_attributes = True
+
+
+class UserBrief(BaseModel):
+    id: str
+    full_name: str
+    avatar_url: Optional[str]
+    role: UserRole
+
+    class Config:
+        from_attributes = True
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+    user: UserResponse
+
+
+class RefreshTokenRequest(BaseModel):
+    refresh_token: str

app/services/auth.py

@@ -0,0 +1,79 @@
+"""Authentication service with JWT tokens and password hashing."""
+
+from datetime import datetime, timedelta
+from typing import Optional
+from passlib.context import CryptContext
+import jwt
+from app.config import settings
+
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+def hash_password(password: str) -> str:
+    """Hash a password using bcrypt."""
+    return pwd_context.hash(password)
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against its hash."""
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def create_access_token(
+    data: dict,
+    expires_delta: Optional[timedelta] = None
+) -> str:
+    """Create a JWT access token."""
+    to_encode = data.copy()
+    expire = datetime.utcnow() + (
+        expires_delta or timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    )
+    to_encode.update({"exp": expire, "type": "access"})
+    return jwt.encode(
+        to_encode,
+        settings.JWT_SECRET_KEY,
+        algorithm=settings.JWT_ALGORITHM
+    )
+
+
+def create_refresh_token(
+    data: dict,
+    expires_delta: Optional[timedelta] = None
+) -> str:
+    """Create a JWT refresh token."""
+    to_encode = data.copy()
+    expire = datetime.utcnow() + (
+        expires_delta or timedelta(days=settings.REFRESH_TOKEN_EXPIRE_DAYS)
+    )
+    to_encode.update({"exp": expire, "type": "refresh"})
+    return jwt.encode(
+        to_encode,
+        settings.JWT_SECRET_KEY,
+        algorithm=settings.JWT_ALGORITHM
+    )
+
+
+def decode_token(token: str) -> Optional[dict]:
+    """Decode and verify a JWT token."""
+    try:
+        payload = jwt.decode(
+            token,
+            settings.JWT_SECRET_KEY,
+            algorithms=[settings.JWT_ALGORITHM]
+        )
+        return payload
+    except jwt.ExpiredSignatureError:
+        return None
+    except jwt.InvalidTokenError:
+        return None
+
+
+def create_tokens(user_id: str, email: str, role: str) -> dict:
+    """Create both access and refresh tokens."""
+    token_data = {"sub": user_id, "email": email, "role": role}
+    return {
+        "access_token": create_access_token(token_data),
+        "refresh_token": create_refresh_token(token_data),
+        "token_type": "bearer",
+    }

app/services/tutor.py

@@ -0,0 +1,359 @@
+"""AI Tutor service using Gemini 2.5 Flash with PostgreSQL pgvector for RAG."""
+
+import json
+import os
+from typing import List, Optional
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_postgres import PGVector
+from langchain.prompts import ChatPromptTemplate
+from langchain.schema import Document
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from pypdf import PdfReader
+from app.config import settings
+from app.schemas.tutor import SourceDocument, GeneratedMCQ
+
+
+class AITutorService:
+    """Enhanced AI Tutor with Gemini 2.5 Flash and PostgreSQL pgvector for RAG."""
+
+    def __init__(self):
+        self.embeddings: Optional[HuggingFaceEmbeddings] = None
+        self.vector_store: Optional[PGVector] = None
+        self.text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=1000,
+            chunk_overlap=200,
+            length_function=len,
+        )
+        self._initialized = False
+        self._llm = None  # Cache LLM instance
+
+    async def initialize(self):
+        """Initialize HuggingFace embeddings and pgvector store."""
+        if self._initialized:
+            return
+
+        print("🔄 Loading embedding model (this may take a moment on first run)...")
+        
+        # Use HuggingFace sentence-transformers for embeddings
+        self.embeddings = HuggingFaceEmbeddings(
+            model_name=settings.EMBEDDING_MODEL,
+            model_kwargs={'device': 'cpu'},
+            encode_kwargs={'normalize_embeddings': True}
+        )
+        
+        print("✅ Embedding model loaded!")
+
+        # Initialize PGVector with PostgreSQL connection
+        # Remove query parameters from URL for PGVector compatibility
+        clean_db_url = settings.DATABASE_URL.replace("+asyncpg", "").split("?")[0]
+        self.vector_store = PGVector(
+            embeddings=self.embeddings,
+            collection_name="documents",
+            connection=clean_db_url,  # psycopg2 format without query params
+            use_jsonb=True,
+        )
+        
+        # Pre-initialize LLM
+        self._llm = self._get_llm(temperature=0.3)
+
+        self._initialized = True
+
+    def _get_llm(self, temperature: float = 0.3) -> ChatGoogleGenerativeAI:
+        """Get Gemini LLM instance."""
+        return ChatGoogleGenerativeAI(
+            model=settings.LLM_MODEL,
+            google_api_key=settings.GOOGLE_API_KEY,
+            temperature=temperature,
+        )
+
+    async def ask_question(
+        self,
+        question: str,
+        lesson_context: Optional[str] = None,
+        module_context: Optional[str] = None,
+    ) -> tuple[str, List[SourceDocument]]:
+        """Answer a question using RAG with lesson/module context."""
+        await self.initialize()
+
+        # Build filter for specific lesson/module if provided
+        filter_dict = {}
+        if lesson_context:
+            filter_dict["lesson_id"] = lesson_context
+        elif module_context:
+            filter_dict["module_id"] = module_context
+
+        # Retrieve relevant documents
+        try:
+            if filter_dict:
+                docs = self.vector_store.similarity_search(
+                    question, k=4, filter=filter_dict
+                )
+            else:
+                docs = self.vector_store.similarity_search(question, k=4)
+        except Exception as e:
+            print(f"⚠️  Vector search error: {e}")
+            # If vector search fails (e.g., no documents yet), provide general answer
+            docs = []
+
+        # Format context
+        context = self._format_context(docs)
+        sources = self._format_sources(docs)
+
+        # Generate answer
+        prompt = ChatPromptTemplate.from_messages([
+            ("system", """You are an AI tutor helping students learn. Answer questions based on the provided context.
+
+INSTRUCTIONS:
+- Be clear, educational, and helpful
+- Use examples when appropriate
+- If the context doesn't have the answer, say so honestly
+- Format with markdown for readability
+
+CONTEXT:
+{context}"""),
+            ("human", "{question}"),
+        ])
+
+        llm = self._llm or self._get_llm(temperature=0.3)
+        chain = prompt | llm
+        response = await chain.ainvoke({"context": context, "question": question})
+
+        return response.content, sources
+
+    async def generate_summary(self, content: str, title: str) -> tuple[str, List[str]]:
+        """Generate a summary with key points from lesson content."""
+        prompt = ChatPromptTemplate.from_messages([
+            ("system", """You are an expert educator. Create a concise summary and extract key learning points.
+
+Return ONLY a valid JSON object (no markdown formatting, no code blocks) with:
+- "summary": A 2-3 paragraph summary of the content
+- "key_points": A list of 5-7 bullet points highlighting the most important concepts
+
+Be educational and clear. Focus on what students need to remember.
+
+IMPORTANT: Return ONLY the JSON object, do NOT wrap it in ```json code blocks."""),
+            ("human", "Summarize this lesson titled '{title}':\n\n{content}"),
+        ])
+
+        llm = self._get_llm(temperature=0.2)
+        chain = prompt | llm
+        response = await chain.ainvoke({"title": title, "content": content})
+
+        try:
+            # Clean response - remove markdown code blocks if present
+            content = response.content.strip()
+            
+            # Remove ```json and ``` wrappers if present
+            if content.startswith("```json"):
+                content = content[7:]  # Remove ```json
+            elif content.startswith("```"):
+                content = content[3:]  # Remove ```
+            
+            if content.endswith("```"):
+                content = content[:-3]  # Remove trailing ```
+            
+            content = content.strip()
+            
+            # Try to parse JSON response
+            result = json.loads(content)
+            return result.get("summary", ""), result.get("key_points", [])
+        except json.JSONDecodeError as e:
+            print(f"⚠️  JSON decode error: {e}")
+            print(f"⚠️  Raw response: {response.content[:500]}")
+            # Fallback: return raw response as summary
+            return response.content, []
+
+    async def generate_mcqs(
+        self,
+        content: str,
+        num_questions: int = 5,
+        difficulty: str = "medium",
+    ) -> List[GeneratedMCQ]:
+        """Generate MCQ questions from content using Gemini."""
+        difficulty_instruction = {
+            "easy": "Focus on basic recall and understanding",
+            "medium": "Include application and analysis questions",
+            "hard": "Focus on synthesis, evaluation, and edge cases",
+        }.get(difficulty, "Include a mix of question difficulties")
+
+        prompt = ChatPromptTemplate.from_messages([
+            ("system", f"""You are an expert test creator. Generate {num_questions} multiple-choice questions based on the provided content.
+
+DIFFICULTY LEVEL: {difficulty}
+INSTRUCTION: {difficulty_instruction}
+
+Return ONLY a valid JSON array (no markdown formatting, no code blocks) where each question has:
+- "question": The question text
+- "options": Array of 4 options (A, B, C, D)
+- "correct_answer": The correct option letter and text (e.g., "A. Photosynthesis")
+- "explanation": Brief explanation of why this is correct
+
+Make questions educational and test real understanding, not just memorization.
+
+IMPORTANT: Return ONLY the JSON array, do NOT wrap it in ```json code blocks."""),
+            ("human", "{content}"),
+        ])
+
+        llm = self._get_llm(temperature=0.4)
+        chain = prompt | llm
+        response = await chain.ainvoke({"content": content})
+
+        try:
+            # Clean response - remove markdown code blocks if present
+            content_str = response.content.strip()
+            
+            # Remove ```json and ``` wrappers if present
+            if content_str.startswith("```json"):
+                content_str = content_str[7:]
+            elif content_str.startswith("```"):
+                content_str = content_str[3:]
+            
+            if content_str.endswith("```"):
+                content_str = content_str[:-3]
+            
+            content_str = content_str.strip()
+            
+            questions_data = json.loads(content_str)
+            return [
+                GeneratedMCQ(
+                    question=q["question"],
+                    options=q["options"],
+                    correct_answer=q["correct_answer"],
+                    explanation=q["explanation"],
+                )
+                for q in questions_data
+            ]
+        except (json.JSONDecodeError, KeyError) as e:
+            print(f"⚠️  Quiz generation error: {e}")
+            print(f"⚠️  Raw response: {response.content[:500]}")
+            return []
+
+    async def generate_hint(
+        self,
+        question: str,
+        context: Optional[str] = None,
+        hint_level: int = 1,
+    ) -> tuple[str, bool]:
+        """Generate progressive hints for a question."""
+        hint_styles = {
+            1: "Give a subtle hint that points the student in the right direction without revealing the answer. Be Socratic — ask guiding questions.",
+            2: "Give a moderate hint that narrows down the possibilities. Mention relevant concepts without stating the answer directly.",
+            3: "Give a strong hint that almost reveals the answer. Provide key information but still require the student to make the final connection.",
+        }
+
+        style = hint_styles.get(hint_level, hint_styles[1])
+
+        prompt = ChatPromptTemplate.from_messages([
+            ("system", f"""You are a patient tutor helping a student who is stuck.
+
+HINT STYLE: {style}
+
+Your goal is to help the student learn, not just give them the answer.
+{f"Use this context if helpful: {context}" if context else ""}"""),
+            ("human", "I need help with this: {question}"),
+        ])
+
+        llm = self._get_llm(temperature=0.5)
+        chain = prompt | llm
+        response = await chain.ainvoke({"question": question})
+
+        has_more_hints = hint_level < 3
+        return response.content, has_more_hints
+
+    def _format_context(self, documents: List[Document]) -> str:
+        """Format retrieved documents into context string."""
+        if not documents:
+            return "No relevant content found."
+
+        parts = []
+        for i, doc in enumerate(documents, 1):
+            source = doc.metadata.get("source", "Unknown")
+            parts.append(f"[Source {i}: {source}]\n{doc.page_content}")
+
+        return "\n\n---\n\n".join(parts)
+
+    def _format_sources(self, documents: List[Document]) -> List[SourceDocument]:
+        """Convert documents to SourceDocument list."""
+        sources = []
+        seen = set()
+        for doc in documents:
+            key = doc.metadata.get("source", "")
+            if key not in seen:
+                seen.add(key)
+                sources.append(
+                    SourceDocument(
+                        content=doc.page_content[:300],
+                        source=doc.metadata.get("source", "Unknown"),
+                        page=doc.metadata.get("page"),
+                    )
+                )
+        return sources
+
+
+    async def index_lesson_content(
+        self,
+        lesson_id: str,
+        module_id: str,
+        title: str,
+        content_text: Optional[str] = None,
+        content_url: Optional[str] = None,
+        content_type: str = "markdown",
+    ) -> bool:
+        """Index lesson content into the vector store."""
+        await self.initialize()
+
+        # Extract content based on type
+        text_to_index = ""
+        
+        if content_type == "markdown" and content_text:
+            text_to_index = content_text
+        elif content_type == "pdf" and content_url:
+            # Extract text from PDF file
+            file_path = os.path.join(settings.UPLOAD_DIR, os.path.basename(content_url))
+            if os.path.exists(file_path):
+                try:
+                    reader = PdfReader(file_path)
+                    pdf_parts = []
+                    # Extract up to 50 pages for full indexing
+                    for i, page in enumerate(reader.pages[:50]):
+                        text = page.extract_text()
+                        if text:
+                            pdf_parts.append(text)
+                    text_to_index = "\n\n".join(pdf_parts)
+                except Exception as e:
+                    print(f"⚠️  PDF extraction error for {file_path}: {e}")
+                    return False
+        
+        if not text_to_index or len(text_to_index.strip()) < 50:
+            print(f"⚠️  No content to index for lesson {lesson_id}")
+            return False
+
+        # Split text into chunks
+        documents = []
+        chunks = self.text_splitter.split_text(text_to_index)
+        
+        for i, chunk in enumerate(chunks):
+            doc = Document(
+                page_content=chunk,
+                metadata={
+                    "source": title,
+                    "lesson_id": lesson_id,
+                    "module_id": module_id,
+                    "chunk_index": i,
+                    "content_type": content_type,
+                }
+            )
+            documents.append(doc)
+
+        # Add documents to vector store
+        try:
+            self.vector_store.add_documents(documents)
+            print(f"✅ Indexed {len(documents)} chunks for lesson '{title}'")
+            return True
+        except Exception as e:
+            print(f"⚠️  Failed to index lesson {lesson_id}: {e}")
+            return False
+
+
+tutor_service = AITutorService()

requirements.txt

@@ -0,0 +1,38 @@
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+python-dotenv==1.0.1
+pydantic==2.10.4
+pydantic-settings==2.7.1
+
+# Database
+sqlalchemy==2.0.36
+psycopg[binary]==3.2.3
+psycopg-pool==3.2.4
+alembic==1.14.0
+psycopg2-binary==2.9.10
+
+# Auth
+pyjwt==2.10.1
+passlib[bcrypt]==1.7.4
+python-multipart==0.0.20
+email-validator==2.1.1
+
+# AI & RAG
+langchain==0.3.14
+langchain-core>=0.3.29,<0.4.0
+langchain-google-genai==2.0.8
+langchain-community==0.3.14
+langchain-postgres==0.0.12
+pgvector>=0.2.5,<0.3.0
+google-generativeai==0.8.3
+sentence-transformers==3.3.1
+langchain-huggingface==0.1.2
+
+# File processing
+pypdf==5.1.0
+aiofiles==24.1.0
+python-magic-bin==0.4.14
+
+# Utilities
+uuid6==2024.7.10
+httpx==0.28.1

uploads/20260307_154626_42dcb39b_resume.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:eb5f461061c8a5042013249c70614e52917f22a88126fee196ff5f1659fe1e97
+size 191823