v5

updated for chatbot

backend/models/collections.py

@@ -13,3 +13,5 @@ TOPIC_QUESTIONS = "topic_questions"
 SESSIONS = "sessions"
 ANSWERS = "answers"
 RESULTS = "results"
+GROUP_TESTS = "group_tests"
+GROUP_TEST_RESULTS = "group_test_results"

backend/requirements.txt

@@ -17,3 +17,4 @@ aiofiles==24.1.0
 pypdf==5.4.0
 python-docx==1.1.2
 faster-whisper==1.0.3
+openpyxl>=3.1.0

backend/routers/admin.py

@@ -1,11 +1,14 @@
 import json
 from fastapi import APIRouter, Depends, HTTPException, Query, UploadFile, File, Form
+from fastapi.responses import StreamingResponse
 from auth.jwt import require_role, get_current_user
 from schemas.admin import (
     JobRoleCreate, JobRoleUpdate,
     QuestionCreate, QuestionUpdate,
     RoleRequirementCreate,
     TopicCreate, TopicUpdate, TopicPublishUpdate,
+    GroupTestCreate, GroupTestUpdate, GroupTestPublishUpdate,
+    ChatbotQueryRequest, ChatbotExportRequest, ChatbotStudentUpdate,
 )
 from services.admin_service import (
     create_role, update_role, delete_role, list_roles,
@@ -21,6 +24,16 @@ from services.job_description_service import (
     list_admin_job_descriptions,
     update_admin_job_description,
     delete_admin_job_description,
+    parse_jd_from_file,
+)
+from services.group_test_service import (
+    create_group_test,
+    list_group_tests,
+    get_group_test,
+    update_group_test,
+    delete_group_test,
+    set_group_test_publish,
+    get_group_test_results_admin,
 )
 from services.analytics_service import get_admin_analytics
 
@@ -417,6 +430,33 @@ async def delete_admin_job_description_endpoint(
     return {"message": "Job description deleted"}
 
 
+@router.post("/job-descriptions/parse-file")
+async def parse_admin_jd_file(
+    file: UploadFile = File(...),
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Upload a JD file (PDF/DOCX/TXT) and extract structured fields via AI (admin only)."""
+    if not file.filename:
+        raise HTTPException(status_code=400, detail="No file provided")
+
+    allowed_ext = {".pdf", ".doc", ".docx", ".txt"}
+    ext = "." + file.filename.rsplit(".", 1)[-1].lower() if "." in file.filename else ""
+    if ext not in allowed_ext:
+        raise HTTPException(status_code=400, detail="Unsupported file type. Allowed: PDF, DOC, DOCX, TXT")
+
+    content = await file.read()
+    if len(content) > 10 * 1024 * 1024:
+        raise HTTPException(status_code=400, detail="File too large. Maximum 10MB")
+
+    try:
+        result = await parse_jd_from_file(file.filename, content)
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to parse JD file: {str(e)}")
+
+
 @router.delete("/users/{user_id}")
 async def delete_admin_user_endpoint(
     user_id: str,
@@ -432,3 +472,143 @@ async def delete_admin_user_endpoint(
         detail = str(e)
         status_code = 404 if "not found" in detail.lower() else 400
         raise HTTPException(status_code=status_code, detail=detail)
+
+
+# ─── Group Tests ─────────────────────────────────────────────────────────────
+
+@router.get("/group-tests")
+async def list_group_tests_endpoint(
+    current_user: dict = Depends(require_role("admin")),
+):
+    items = await list_group_tests(only_published=False)
+    return {"items": items}
+
+
+@router.post("/group-tests")
+async def create_group_test_endpoint(
+    request: GroupTestCreate,
+    current_user: dict = Depends(require_role("admin")),
+):
+    try:
+        result = await create_group_test(
+            name=request.name,
+            description=request.description,
+            topic_ids=request.topic_ids,
+            time_limit_minutes=request.time_limit_minutes,
+            max_attempts=request.max_attempts,
+            created_by=current_user["user_id"],
+        )
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/group-tests/{group_test_id}")
+async def get_group_test_endpoint(
+    group_test_id: str,
+    current_user: dict = Depends(require_role("admin")),
+):
+    try:
+        return await get_group_test(group_test_id)
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+
+@router.put("/group-tests/{group_test_id}")
+async def update_group_test_endpoint(
+    group_test_id: str,
+    request: GroupTestUpdate,
+    current_user: dict = Depends(require_role("admin")),
+):
+    try:
+        return await update_group_test(group_test_id, request.model_dump(exclude_none=True))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/group-tests/{group_test_id}")
+async def delete_group_test_endpoint(
+    group_test_id: str,
+    current_user: dict = Depends(require_role("admin")),
+):
+    success = await delete_group_test(group_test_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="Group test not found")
+    return {"message": "Group test deleted"}
+
+
+@router.patch("/group-tests/{group_test_id}/publish")
+async def publish_group_test_endpoint(
+    group_test_id: str,
+    request: GroupTestPublishUpdate,
+    current_user: dict = Depends(require_role("admin")),
+):
+    try:
+        return await set_group_test_publish(group_test_id, request.is_published)
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+
+@router.get("/group-tests/{group_test_id}/results")
+async def get_group_test_results_endpoint(
+    group_test_id: str,
+    current_user: dict = Depends(require_role("admin")),
+):
+    results = await get_group_test_results_admin(group_test_id)
+    return {"items": results}
+
+
+# ─── Chatbot ──────────────────────────────────────────────────────────────────
+from services.chatbot_service import (
+    process_chatbot_query,
+    update_student_info,
+    generate_excel,
+)
+
+
+@router.post("/chatbot/query")
+async def chatbot_query(
+    request: ChatbotQueryRequest,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """AI-powered student filter — returns ranked student rows."""
+    try:
+        result = await process_chatbot_query(request.query, request.jd_id)
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/chatbot/export-excel")
+async def chatbot_export_excel(
+    request: ChatbotExportRequest,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Generate styled Excel (.xlsx) from current chatbot result rows."""
+    try:
+        bio = generate_excel(
+            rows=request.rows,
+            topic_columns=request.topic_columns,
+            group_test_name=request.group_test_name,
+        )
+        safe_name = request.group_test_name.replace(" ", "_").replace("/", "-")[:40]
+        filename = f"{safe_name}_students.xlsx"
+        return StreamingResponse(
+            bio,
+            media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.patch("/chatbot/students")
+async def chatbot_update_student(
+    request: ChatbotStudentUpdate,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Admin corrects a student's reg_no or name."""
+    try:
+        return await update_student_info(request.user_id, request.reg_no, request.name)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))

backend/routers/profile.py

@@ -10,7 +10,18 @@ from services.job_description_service import (
     list_my_job_descriptions,
     update_my_job_description,
     delete_my_job_description,
+    parse_jd_from_file,
 )
+from services.group_test_service import (
+    list_group_tests,
+    get_group_test,
+    start_group_test_attempt,
+    get_group_test_result,
+    link_topic_session,
+    get_my_group_test_results,
+    get_my_group_test_attempt,
+)
+from fastapi import UploadFile, File
 
 router = APIRouter()
 
@@ -33,6 +44,7 @@ async def get_profile(current_user: dict = Depends(get_current_user)):
         "speech_settings": {
             "voice_gender": (user or {}).get("speech_settings", {}).get("voice_gender", "female"),
         },
+        "reg_no": (user or {}).get("reg_no") or None,
     }
 
     # Get resume info
@@ -169,3 +181,102 @@ async def delete_my_job_description_endpoint(
     if not success:
         raise HTTPException(status_code=404, detail="Job description not found")
     return {"message": "Job description deleted"}
+
+
+@router.post("/job-descriptions/parse-file")
+async def parse_jd_file_for_user(
+    file: UploadFile = File(...),
+    current_user: dict = Depends(get_current_user),
+):
+    """Upload a JD file (PDF/DOCX/TXT) and extract structured fields via AI."""
+    if not file.filename:
+        raise HTTPException(status_code=400, detail="No file provided")
+
+    allowed_ext = {".pdf", ".doc", ".docx", ".txt"}
+    ext = "." + file.filename.rsplit(".", 1)[-1].lower() if "." in file.filename else ""
+    if ext not in allowed_ext:
+        raise HTTPException(status_code=400, detail="Unsupported file type. Allowed: PDF, DOC, DOCX, TXT")
+
+    content = await file.read()
+    if len(content) > 10 * 1024 * 1024:
+        raise HTTPException(status_code=400, detail="File too large. Maximum 10MB")
+
+    try:
+        result = await parse_jd_from_file(file.filename, content)
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to parse JD file: {str(e)}")
+
+
+# ─── Group Tests (student) ───────────────────────────────────────────────────
+
+@router.get("/group-tests")
+async def list_available_group_tests(
+    current_user: dict = Depends(get_current_user),
+):
+    """List published group tests available to students."""
+    items = await list_group_tests(only_published=True)
+    return {"items": items}
+
+
+@router.get("/group-tests/my-results")
+async def my_group_test_results(
+    current_user: dict = Depends(get_current_user),
+):
+    """List all group test results for the current student."""
+    items = await get_my_group_test_results(current_user["user_id"])
+    return {"items": items}
+
+
+@router.post("/group-tests/{group_test_id}/start")
+async def start_group_test(
+    group_test_id: str,
+    current_user: dict = Depends(get_current_user),
+):
+    """Start a new attempt for a group test."""
+    try:
+        result = await start_group_test_attempt(group_test_id, current_user["user_id"])
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/group-tests/{group_test_id}/my-attempt")
+async def get_my_attempt(
+    group_test_id: str,
+    current_user: dict = Depends(get_current_user),
+):
+    """Get student's latest attempt at a group test."""
+    result = await get_my_group_test_attempt(group_test_id, current_user["user_id"])
+    return result  # may be None
+
+
+@router.get("/group-tests/results/{result_id}")
+async def get_result_detail(
+    result_id: str,
+    current_user: dict = Depends(get_current_user),
+):
+    """Get full detail of a group test result."""
+    try:
+        return await get_group_test_result(result_id, current_user["user_id"])
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+
+@router.post("/group-tests/results/{result_id}/link-topic")
+async def link_topic_to_result(
+    result_id: str,
+    request_data: dict,
+    current_user: dict = Depends(get_current_user),
+):
+    """Link a completed interview session to a topic inside a group test result."""
+    topic_id = (request_data.get("topic_id") or "").strip()
+    session_id = (request_data.get("session_id") or "").strip()
+    if not topic_id or not session_id:
+        raise HTTPException(status_code=400, detail="topic_id and session_id are required")
+    try:
+        return await link_topic_session(result_id, current_user["user_id"], topic_id, session_id)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))

backend/schemas/admin.py

@@ -79,8 +79,52 @@ class RoleRequirementCreate(BaseModel):
     level: str = "intermediate"
 
 
+class GroupTestCreate(BaseModel):
+    name: str
+    description: Optional[str] = None
+    topic_ids: List[str]
+    time_limit_minutes: Optional[int] = None
+    max_attempts: int = 1
+
+
+class GroupTestUpdate(BaseModel):
+    name: Optional[str] = None
+    description: Optional[str] = None
+    topic_ids: Optional[List[str]] = None
+    time_limit_minutes: Optional[int] = None
+    max_attempts: Optional[int] = None
+
+
+class GroupTestPublishUpdate(BaseModel):
+    is_published: bool
+
+
+class LinkTopicSessionRequest(BaseModel):
+    topic_id: str
+    session_id: str
+
+
 class RoleRequirementResponse(BaseModel):
     id: str
     role_id: str
     skill: str
     level: str
+
+
+# ── Chatbot ───────────────────────────────────────────────────────────────────
+
+class ChatbotQueryRequest(BaseModel):
+    query: str
+    jd_id: Optional[str] = None
+
+
+class ChatbotExportRequest(BaseModel):
+    rows: List[dict]
+    topic_columns: List[dict]
+    group_test_name: str
+
+
+class ChatbotStudentUpdate(BaseModel):
+    user_id: str
+    reg_no: Optional[str] = None
+    name: Optional[str] = None

backend/services/admin_service.py

@@ -600,6 +600,7 @@ async def list_admin_users(limit: int = 500) -> list:
                 "name": normalized.get("name", ""),
                 "email": normalized.get("email", ""),
                 "role": normalized.get("role", "student"),
+                "reg_no": normalized.get("reg_no") or None,
                 "created_at": normalized.get("created_at", ""),
                 "interview_count": interview_map.get(user_id, 0),
                 "report_count": report_map.get(user_id, 0),

backend/services/chatbot_service.py

@@ -0,0 +1,405 @@
+"""Admin chatbot service — AI-powered student filtering & report generation."""
+
+import json
+import re
+from collections import defaultdict
+from io import BytesIO
+
+from bson import ObjectId
+from openpyxl import Workbook
+from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
+from openpyxl.utils import get_column_letter
+
+from database import get_db
+from models.collections import (
+    GROUP_TESTS,
+    GROUP_TEST_RESULTS,
+    JOB_DESCRIPTIONS,
+    SKILLS,
+    TOPICS,
+    USERS,
+)
+from services.group_test_service import _refresh_topic_statuses
+from utils.gemini import call_gemini
+from utils.helpers import str_objectids
+
+
+# ─── Gemini query parser ─────────────────────────────────────────────────────
+
+async def _parse_query(query: str, group_tests: list[dict], jd_content: str | None) -> dict:
+    """Ask Gemini to extract structured filter parameters from a natural-language query."""
+    gt_list = [{"id": gt["id"], "name": gt["name"]} for gt in group_tests]
+
+    jd_context = ""
+    if jd_content:
+        jd_context = (
+            f"\n\nJob Description:\n{jd_content}\n"
+            "Use this JD to rank students by skill relevance when use_jd_ranking is true."
+        )
+
+    prompt = (
+        f'Admin query: "{query}"\n\n'
+        f"Available group tests: {json.dumps(gt_list)}"
+        f"{jd_context}\n\n"
+        "Extract filter parameters and return ONLY a JSON object (no markdown, no extra text):\n"
+        "{\n"
+        '  "group_test_id": "<id from the list, or null if none matches>",\n'
+        '  "group_test_name": "<matched name or null>",\n'
+        '  "top_k": <integer or null>,\n'
+        '  "min_score": <number 0-100 or null>,\n'
+        '  "use_jd_ranking": <true if JD was provided and should influence ranking>,\n'
+        '  "response_message": "<short 1-2 sentence message describing the filter result>"\n'
+        "}\n\n"
+        "Rules:\n"
+        "- Match group_test_id to the best-fitting group test. null = show all students across all tests.\n"
+        "- top_k: number from phrases like 'top 5', 'top k', 'best 10'. null = all.\n"
+        "- min_score: extract from 'score above 70', 'minimum 80%'. null = no filter.\n"
+        "- response_message: friendly description of what was filtered.\n"
+        "Return ONLY valid JSON, no other text."
+    )
+
+    raw = await call_gemini(prompt)
+    cleaned = raw.strip()
+    if cleaned.startswith("```"):
+        cleaned = re.sub(r"```[a-z]*\n?", "", cleaned).strip().rstrip("`").strip()
+    try:
+        return json.loads(cleaned)
+    except Exception:
+        # Fallback: return empty params so the caller can show a helpful message
+        return {
+            "group_test_id": None,
+            "group_test_name": None,
+            "top_k": None,
+            "min_score": None,
+            "use_jd_ranking": False,
+            "response_message": "I couldn't understand the query. Please try something like: 'top 5 students in SWE group'.",
+        }
+
+
+# ─── Data helpers ─────────────────────────────────────────────────────────────
+
+async def _user_info(user_id: str, db) -> dict:
+    try:
+        user = await db[USERS].find_one({"_id": ObjectId(user_id)})
+    except Exception:
+        user = None
+    if not user:
+        return {"reg_no": "N/A", "name": "", "email": ""}
+    return {
+        "reg_no": user.get("reg_no") or "N/A",
+        "name": user.get("name", ""),
+        "email": user.get("email", ""),
+    }
+
+
+async def _jd_skills(jd_id: str, db) -> tuple[str | None, list[str]]:
+    """Return (jd_content_str, required_skills_list)."""
+    try:
+        doc = await db[JOB_DESCRIPTIONS].find_one({"_id": ObjectId(jd_id)})
+    except Exception:
+        doc = None
+    if not doc:
+        return None, []
+    content = f"Title: {doc.get('title', '')}\n{doc.get('description', '')}"
+    return content, doc.get("required_skills") or []
+
+
+def _skill_match_pct(student_skills: list[str], jd_skills: list[str]) -> float | None:
+    if not jd_skills:
+        return None
+    s_lower = [s.lower() for s in student_skills]
+    j_lower = [s.lower() for s in jd_skills]
+    matched = sum(1 for j in j_lower if any(j in s or s in j for s in s_lower))
+    return round(matched / len(j_lower) * 100, 1)
+
+
+# ─── Main query processor ────────────────────────────────────────────────────
+
+async def process_chatbot_query(query: str, jd_id: str | None) -> dict:
+    """Parse admin query, aggregate student data, apply filters, return ranked rows."""
+    db = get_db()
+
+    # Fetch all group tests
+    gt_cursor = db[GROUP_TESTS].find({}).sort("created_at", -1)
+    gt_docs = await gt_cursor.to_list(length=300)
+    all_group_tests = [
+        {
+            "id": str(d["_id"]),
+            "name": d.get("name", ""),
+            "topic_ids": d.get("topic_ids") or [],
+        }
+        for d in gt_docs
+    ]
+
+    # Fetch JD if provided
+    jd_content, jd_req_skills = (None, [])
+    if jd_id:
+        jd_content, jd_req_skills = await _jd_skills(jd_id, db)
+
+    # Let Gemini parse the query
+    parsed = await _parse_query(query, all_group_tests, jd_content)
+
+    group_test_id: str | None = parsed.get("group_test_id")
+    top_k: int | None = parsed.get("top_k")
+    min_score: float | None = parsed.get("min_score")
+    use_jd_ranking: bool = bool(parsed.get("use_jd_ranking")) and bool(jd_req_skills)
+    response_message: str = parsed.get("response_message") or "Here are the filtered results."
+
+    # Build topic column list from the matched group test
+    topic_columns: list[dict] = []
+    group_test_name: str = ""
+
+    if group_test_id:
+        gt_doc = next((g for g in all_group_tests if g["id"] == group_test_id), None)
+        if gt_doc:
+            group_test_name = gt_doc["name"]
+            for tid in gt_doc["topic_ids"]:
+                try:
+                    t = await db[TOPICS].find_one({"_id": ObjectId(tid)})
+                except Exception:
+                    t = None
+                if t:
+                    topic_columns.append({"id": tid, "name": t.get("name", tid)})
+
+    # Fetch relevant results
+    results_filter = {"group_test_id": group_test_id} if group_test_id else {}
+    results_cursor = db[GROUP_TEST_RESULTS].find(results_filter)
+    results_docs = await results_cursor.to_list(length=2000)
+
+    # Group by user_id; pick best attempt per user per group_test
+    # Key: (user_id, group_test_id) → list of attempts
+    attempts_map: dict[tuple, list] = defaultdict(list)
+    for r in results_docs:
+        key = (r.get("user_id", ""), r.get("group_test_id", ""))
+        attempts_map[key].append(r)
+
+    rows: list[dict] = []
+    seen_users: set[str] = set()
+
+    for (uid, gt_id), attempts in attempts_map.items():
+        if not uid:
+            continue
+
+        # Refresh topic statuses and choose best attempt
+        best = None
+        for attempt in attempts:
+            attempt = await _refresh_topic_statuses(attempt, db)
+            score = attempt.get("overall_score") or 0
+            if best is None or score > (best.get("overall_score") or 0):
+                best = attempt
+
+        user = await _user_info(uid, db)
+
+        # Per-topic scores from best attempt
+        topic_scores: dict[str, dict] = {}
+        for tr in best.get("topic_results") or []:
+            tid = tr.get("topic_id", "")
+            topic_scores[tid] = {
+                "topic_name": tr.get("topic_name", ""),
+                "score": tr.get("overall_score"),
+                "status": tr.get("status", "pending"),
+            }
+
+        # JD skill match
+        skill_match: float | None = None
+        if use_jd_ranking:
+            skills_doc = await db[SKILLS].find_one({"user_id": uid})
+            student_skills = (skills_doc or {}).get("skills") or []
+            skill_match = _skill_match_pct(student_skills, jd_req_skills)
+
+        row = {
+            "user_id": uid,
+            "reg_no": user["reg_no"],
+            "name": user["name"],
+            "email": user["email"],
+            "group_test_id": gt_id,
+            "group_test_name": best.get("group_test_name") or group_test_name,
+            "overall_score": round(best.get("overall_score") or 0, 1),
+            "total_attempts": len(attempts),
+            "status": best.get("status", "in_progress"),
+            "topic_scores": topic_scores,
+            "skill_match": skill_match,
+            "rank": 0,  # assigned below
+        }
+        rows.append(row)
+
+    # If multiple group tests queried (no filter), collect unique topic columns
+    if not group_test_id:
+        topic_set: dict[str, str] = {}
+        for r in rows:
+            for tid, ts in r["topic_scores"].items():
+                if tid not in topic_set:
+                    topic_set[tid] = ts["topic_name"]
+        topic_columns = [{"id": tid, "name": name} for tid, name in topic_set.items()]
+
+    # Sort
+    if use_jd_ranking:
+        rows.sort(
+            key=lambda r: (r["skill_match"] or 0) * 0.4 + (r["overall_score"] or 0) * 0.6,
+            reverse=True,
+        )
+    else:
+        rows.sort(key=lambda r: r["overall_score"] or 0, reverse=True)
+
+    # Min score filter
+    if min_score is not None:
+        rows = [r for r in rows if (r["overall_score"] or 0) >= min_score]
+
+    # Assign ranks
+    for i, row in enumerate(rows):
+        row["rank"] = i + 1
+
+    # Top-k slice
+    if top_k and top_k > 0:
+        rows = rows[:top_k]
+
+    return {
+        "message": response_message,
+        "group_test_name": group_test_name or "All Group Tests",
+        "group_test_id": group_test_id,
+        "topic_columns": topic_columns,
+        "rows": rows,
+        "total": len(rows),
+    }
+
+
+# ─── Update student ───────────────────────────────────────────────────────────
+
+async def update_student_info(user_id: str, reg_no: str | None, name: str | None) -> dict:
+    """Allow admin to correct a student's reg_no or name."""
+    db = get_db()
+    update: dict = {}
+    if reg_no is not None:
+        reg_no = reg_no.strip()
+        if reg_no:
+            # Uniqueness check
+            existing = await db[USERS].find_one(
+                {"reg_no": reg_no, "_id": {"$ne": ObjectId(user_id)}}
+            )
+            if existing:
+                raise ValueError("This register number is already used by another student.")
+            update["reg_no"] = reg_no
+    if name is not None:
+        name = name.strip()
+        if name:
+            update["name"] = name
+    if not update:
+        raise ValueError("Nothing to update.")
+    await db[USERS].update_one({"_id": ObjectId(user_id)}, {"$set": update})
+    user = await db[USERS].find_one({"_id": ObjectId(user_id)})
+    return {
+        "user_id": user_id,
+        "reg_no": (user or {}).get("reg_no") or "N/A",
+        "name": (user or {}).get("name", ""),
+        "email": (user or {}).get("email", ""),
+    }
+
+
+# ─── Excel export ─────────────────────────────────────────────────────────────
+
+_HEADER_FILL = PatternFill(start_color="1F4E79", end_color="1F4E79", fill_type="solid")
+_ALT_FILL = PatternFill(start_color="D6E4F0", end_color="D6E4F0", fill_type="solid")
+_SCORE_FILL = PatternFill(start_color="E8F5E9", end_color="E8F5E9", fill_type="solid")
+_HEADER_FONT = Font(name="Calibri", bold=True, color="FFFFFF", size=11)
+_DATA_FONT = Font(name="Calibri", size=10)
+_BOLD_DATA_FONT = Font(name="Calibri", bold=True, size=10)
+_CENTER = Alignment(horizontal="center", vertical="center", wrap_text=True)
+_LEFT = Alignment(horizontal="left", vertical="center")
+
+
+def _thin_border() -> Border:
+    s = Side(style="thin", color="B0BEC5")
+    return Border(left=s, right=s, top=s, bottom=s)
+
+
+def generate_excel(rows: list[dict], topic_columns: list[dict], group_test_name: str) -> BytesIO:
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "Students"
+
+    border = _thin_border()
+
+    # ── Header row ────────────────────────────────────────────────────────────
+    headers = ["Rank", "Reg No", "Name", "Email"]
+    for tc in topic_columns:
+        headers.append(f"{tc['name']}\nScore")
+    headers += ["Overall\nScore", "Attempts", "Status"]
+    if any(r.get("skill_match") is not None for r in rows):
+        headers.append("JD Match\n(%)")
+
+    for col_idx, header in enumerate(headers, 1):
+        cell = ws.cell(row=1, column=col_idx, value=header)
+        cell.font = _HEADER_FONT
+        cell.fill = _HEADER_FILL
+        cell.alignment = _CENTER
+        cell.border = border
+    ws.row_dimensions[1].height = 36
+
+    # ── Data rows ─────────────────────────────────────────────────────────────
+    for row_num, row in enumerate(rows, 2):
+        use_alt = row_num % 2 == 0
+        row_fill = _ALT_FILL if use_alt else None
+
+        data: list = [
+            row.get("rank", row_num - 1),
+            row.get("reg_no", ""),
+            row.get("name", ""),
+            row.get("email", ""),
+        ]
+
+        for tc in topic_columns:
+            ts = row.get("topic_scores", {}).get(tc["id"], {})
+            score = ts.get("score")
+            data.append(f"{score:.1f}%" if score is not None else "—")
+
+        overall = row.get("overall_score")
+        data.append(f"{overall:.1f}%" if overall is not None else "—")
+        data.append(row.get("total_attempts", 1))
+        data.append((row.get("status") or "").replace("_", " ").title())
+
+        if any(r.get("skill_match") is not None for r in rows):
+            sm = row.get("skill_match")
+            data.append(f"{sm:.1f}%" if sm is not None else "—")
+
+        for col_idx, value in enumerate(data, 1):
+            cell = ws.cell(row=row_num, column=col_idx, value=value)
+            cell.border = border
+            cell.font = _DATA_FONT
+            if col_idx in (1,):  # rank → bold + centered
+                cell.font = _BOLD_DATA_FONT
+                cell.alignment = _CENTER
+            elif col_idx in (2, 3, 4):
+                cell.alignment = _LEFT
+            else:
+                cell.alignment = _CENTER
+            if row_fill:
+                cell.fill = row_fill
+
+        ws.row_dimensions[row_num].height = 20
+
+    # ── Column widths ────────────────────────────────────────���─────────────────
+    col_widths = [6, 16, 22, 28]
+    for _ in topic_columns:
+        col_widths.append(14)
+    col_widths += [14, 10, 14]
+    if any(r.get("skill_match") is not None for r in rows):
+        col_widths.append(12)
+
+    for i, width in enumerate(col_widths, 1):
+        ws.column_dimensions[get_column_letter(i)].width = width
+
+    # ── Title row above headers ────────────────────────────────────────────────
+    ws.insert_rows(1)
+    title_cell = ws.cell(row=1, column=1, value=f"Student Results — {group_test_name}")
+    title_cell.font = Font(name="Calibri", bold=True, size=13, color="1F4E79")
+    title_cell.alignment = _LEFT
+    ws.merge_cells(start_row=1, start_column=1, end_row=1, end_column=max(len(headers), 5))
+    ws.row_dimensions[1].height = 28
+
+    # ── Freeze header row ──────────────────────────────────────────────────────
+    ws.freeze_panes = "A3"
+
+    bio = BytesIO()
+    wb.save(bio)
+    bio.seek(0)
+    return bio

backend/services/group_test_service.py

@@ -0,0 +1,295 @@
+from bson import ObjectId
+from database import get_db
+from models.collections import GROUP_TESTS, GROUP_TEST_RESULTS, TOPICS, USERS, RESULTS
+from utils.helpers import utc_now, str_objectid, str_objectids
+
+
+# ─── helpers ─────────────────────────────────────────────────────────────────
+
+async def _enrich_group_test(doc: dict, db) -> dict:
+    """Attach topic names to a group test document."""
+    enriched = str_objectid(doc)
+    topics = []
+    for tid in (doc.get("topic_ids") or []):
+        try:
+            t = await db[TOPICS].find_one({"_id": ObjectId(tid)})
+        except Exception:
+            t = None
+        if t:
+            topics.append({"id": str(t["_id"]), "name": t.get("name", "")})
+    enriched["topics"] = topics
+    return enriched
+
+
+async def _refresh_topic_statuses(result: dict, db) -> dict:
+    """Check RESULTS collection for each topic session and update statuses in-place."""
+    topic_results = result.get("topic_results") or []
+    updated = False
+    for tr in topic_results:
+        if tr.get("status") == "completed":
+            continue
+        session_id = tr.get("session_id")
+        if not session_id:
+            continue
+        report = await db[RESULTS].find_one({"session_id": session_id})
+        if report:
+            tr["status"] = "completed"
+            tr["overall_score"] = report.get("overall_score", 0)
+            tr["total_questions"] = report.get("total_questions", 0)
+            tr["completed_at"] = report.get("completed_at")
+            updated = True
+
+    if updated:
+        result_id = str(result.get("_id") or result.get("id", ""))
+        all_done = all(tr.get("status") == "completed" for tr in topic_results)
+        if all_done:
+            scores = [tr.get("overall_score") or 0 for tr in topic_results]
+            overall = round(sum(scores) / len(scores), 1) if scores else 0.0
+            await db[GROUP_TEST_RESULTS].update_one(
+                {"_id": ObjectId(result_id)},
+                {
+                    "$set": {
+                        "topic_results": topic_results,
+                        "status": "completed",
+                        "overall_score": overall,
+                        "completed_at": utc_now(),
+                    }
+                },
+            )
+            result["status"] = "completed"
+            result["overall_score"] = overall
+        else:
+            await db[GROUP_TEST_RESULTS].update_one(
+                {"_id": ObjectId(result_id)},
+                {"$set": {"topic_results": topic_results}},
+            )
+        result["topic_results"] = topic_results
+    return result
+
+
+# ─── Admin CRUD ───────────────────────────────────────────────────────────────
+
+async def create_group_test(
+    name: str,
+    description: str | None,
+    topic_ids: list[str],
+    time_limit_minutes: int | None,
+    max_attempts: int,
+    created_by: str,
+) -> dict:
+    db = get_db()
+
+    if not topic_ids:
+        raise ValueError("At least one topic is required")
+
+    # Validate every topic exists
+    for tid in topic_ids:
+        try:
+            t = await db[TOPICS].find_one({"_id": ObjectId(tid)})
+        except Exception:
+            raise ValueError(f"Invalid topic ID: {tid}")
+        if not t:
+            raise ValueError(
+                f"Topic with ID '{tid}' does not exist. Create it in Topics before adding here."
+            )
+
+    doc = {
+        "name": name.strip(),
+        "description": (description or "").strip() or None,
+        "topic_ids": topic_ids,
+        "time_limit_minutes": time_limit_minutes,
+        "max_attempts": max(1, int(max_attempts)),
+        "is_published": False,
+        "created_by": created_by,
+        "created_at": utc_now(),
+    }
+    result = await db[GROUP_TESTS].insert_one(doc)
+    doc["_id"] = result.inserted_id
+    return await _enrich_group_test(doc, db)
+
+
+async def list_group_tests(only_published: bool = False) -> list:
+    db = get_db()
+    query = {"is_published": True} if only_published else {}
+    cursor = db[GROUP_TESTS].find(query).sort("created_at", -1)
+    docs = await cursor.to_list(length=200)
+    return [await _enrich_group_test(d, db) for d in docs]
+
+
+async def get_group_test(group_test_id: str) -> dict:
+    db = get_db()
+    doc = await db[GROUP_TESTS].find_one({"_id": ObjectId(group_test_id)})
+    if not doc:
+        raise ValueError("Group test not found")
+    return await _enrich_group_test(doc, db)
+
+
+async def update_group_test(group_test_id: str, data: dict) -> dict:
+    db = get_db()
+
+    # Validate topic IDs if provided
+    if "topic_ids" in data and data["topic_ids"] is not None:
+        if not data["topic_ids"]:
+            raise ValueError("At least one topic is required")
+        for tid in data["topic_ids"]:
+            try:
+                t = await db[TOPICS].find_one({"_id": ObjectId(tid)})
+            except Exception:
+                raise ValueError(f"Invalid topic ID: {tid}")
+            if not t:
+                raise ValueError(
+                    f"Topic with ID '{tid}' does not exist. Create it in Topics before adding here."
+                )
+
+    update_data = {k: v for k, v in data.items() if v is not None}
+    if "max_attempts" in update_data:
+        update_data["max_attempts"] = max(1, int(update_data["max_attempts"]))
+    update_data["updated_at"] = utc_now()
+
+    await db[GROUP_TESTS].update_one(
+        {"_id": ObjectId(group_test_id)}, {"$set": update_data}
+    )
+    return await get_group_test(group_test_id)
+
+
+async def delete_group_test(group_test_id: str) -> bool:
+    db = get_db()
+    result = await db[GROUP_TESTS].delete_one({"_id": ObjectId(group_test_id)})
+    return result.deleted_count > 0
+
+
+async def set_group_test_publish(group_test_id: str, is_published: bool) -> dict:
+    db = get_db()
+    await db[GROUP_TESTS].update_one(
+        {"_id": ObjectId(group_test_id)},
+        {"$set": {"is_published": is_published, "updated_at": utc_now()}},
+    )
+    return await get_group_test(group_test_id)
+
+
+async def get_group_test_results_admin(group_test_id: str) -> list:
+    """All student results for a given group test (admin view)."""
+    db = get_db()
+    cursor = db[GROUP_TEST_RESULTS].find({"group_test_id": group_test_id}).sort(
+        "started_at", -1
+    )
+    docs = await cursor.to_list(length=500)
+    return str_objectids(docs)
+
+
+# ─── Student ──────────────────────────────────────────────────────────────────
+
+async def start_group_test_attempt(group_test_id: str, user_id: str) -> dict:
+    db = get_db()
+
+    group_test = await db[GROUP_TESTS].find_one({"_id": ObjectId(group_test_id)})
+    if not group_test:
+        raise ValueError("Group test not found")
+    if not group_test.get("is_published"):
+        raise ValueError("This group test is not available")
+
+    max_attempts = int(group_test.get("max_attempts") or 1)
+    attempt_count = await db[GROUP_TEST_RESULTS].count_documents(
+        {"group_test_id": group_test_id, "user_id": user_id}
+    )
+    if attempt_count >= max_attempts:
+        raise ValueError(
+            f"You have reached the maximum number of attempts ({max_attempts}) for this group test."
+        )
+
+    user = await db[USERS].find_one({"_id": ObjectId(user_id)})
+
+    topic_results = []
+    for tid in (group_test.get("topic_ids") or []):
+        t = await db[TOPICS].find_one({"_id": ObjectId(tid)})
+        topic_results.append(
+            {
+                "topic_id": tid,
+                "topic_name": t.get("name", "") if t else "",
+                "session_id": None,
+                "status": "pending",
+                "overall_score": None,
+                "total_questions": None,
+                "completed_at": None,
+            }
+        )
+
+    doc = {
+        "group_test_id": group_test_id,
+        "group_test_name": group_test.get("name", ""),
+        "user_id": user_id,
+        "user_name": (user or {}).get("name", ""),
+        "user_email": (user or {}).get("email", ""),
+        "attempt_number": attempt_count + 1,
+        "topic_results": topic_results,
+        "overall_score": None,
+        "status": "in_progress",
+        "started_at": utc_now(),
+        "completed_at": None,
+        "time_limit_minutes": group_test.get("time_limit_minutes"),
+    }
+    result = await db[GROUP_TEST_RESULTS].insert_one(doc)
+    doc["_id"] = result.inserted_id
+    return str_objectid(doc)
+
+
+async def get_group_test_result(result_id: str, user_id: str) -> dict:
+    db = get_db()
+    result = await db[GROUP_TEST_RESULTS].find_one({"_id": ObjectId(result_id)})
+    if not result:
+        raise ValueError("Group test result not found")
+    if result.get("user_id") != user_id:
+        raise ValueError("Unauthorized")
+    result = await _refresh_topic_statuses(result, db)
+    return str_objectid(result)
+
+
+async def link_topic_session(
+    result_id: str, user_id: str, topic_id: str, session_id: str
+) -> dict:
+    """Store session_id for a topic so its completion can be tracked."""
+    db = get_db()
+    result = await db[GROUP_TEST_RESULTS].find_one({"_id": ObjectId(result_id)})
+    if not result:
+        raise ValueError("Group test result not found")
+    if result.get("user_id") != user_id:
+        raise ValueError("Unauthorized")
+
+    topic_results = result.get("topic_results") or []
+    found = False
+    for tr in topic_results:
+        if tr.get("topic_id") == topic_id:
+            tr["session_id"] = session_id
+            if tr.get("status") == "pending":
+                tr["status"] = "in_progress"
+            found = True
+            break
+
+    if not found:
+        raise ValueError("Topic not found in this group test")
+
+    await db[GROUP_TEST_RESULTS].update_one(
+        {"_id": ObjectId(result_id)},
+        {"$set": {"topic_results": topic_results}},
+    )
+    return await get_group_test_result(result_id, user_id)
+
+
+async def get_my_group_test_results(user_id: str) -> list:
+    db = get_db()
+    cursor = db[GROUP_TEST_RESULTS].find({"user_id": user_id}).sort("started_at", -1)
+    docs = await cursor.to_list(length=100)
+    return str_objectids(docs)
+
+
+async def get_my_group_test_attempt(group_test_id: str, user_id: str) -> dict | None:
+    """Return latest attempt result for a group test, or None."""
+    db = get_db()
+    doc = await db[GROUP_TEST_RESULTS].find_one(
+        {"group_test_id": group_test_id, "user_id": user_id},
+        sort=[("attempt_number", -1)],
+    )
+    if not doc:
+        return None
+    doc = await _refresh_topic_statuses(doc, db)
+    return str_objectid(doc)

backend/services/job_description_service.py

@@ -3,6 +3,8 @@ from bson import ObjectId
 from database import get_db
 from models.collections import JOB_DESCRIPTIONS
 from utils.helpers import utc_now, str_objectid, str_objectids
+from utils.resume_text import extract_resume_text
+from utils.gemini import parse_jd_with_gemini
 
 
 def _normalize_required_skills(required_skills):
@@ -160,3 +162,11 @@ async def get_job_description_for_user(user_id: str, jd_id: str) -> dict:
     if not doc:
         raise ValueError("Job description not found")
     return str_objectid(doc)
+
+
+async def parse_jd_from_file(filename: str, file_content: bytes) -> dict:
+    """Extract text from an uploaded JD file and use AI to parse it into structured fields."""
+    text = extract_resume_text(filename, file_content)
+    if not text or len(text.strip()) < 20:
+        raise ValueError("Could not extract readable text from the uploaded file")
+    return await parse_jd_with_gemini(text)

backend/services/resume_service.py

@@ -1,20 +1,56 @@
 import os
+import re
 import aiofiles
 from database import get_db
-from models.collections import RESUMES, SKILLS
+from models.collections import RESUMES, SKILLS, USERS
 from utils.helpers import utc_now, str_objectid
 from utils.gemini import parse_resume_with_gemini
 from utils.resume_text import extract_resume_text
 from utils.skills import normalize_skill_list
 from config import get_settings
+from bson import ObjectId
 
 settings = get_settings()
 
+# Expected filename format: {12 digits}_{name}.{ext}
+# Example: 714023243122_Sajith J.pdf
+_RESUME_FILENAME_RE = re.compile(r'^(\d{12})_(.+)\.(pdf|doc|docx|txt)$', re.IGNORECASE)
+
+
+def extract_reg_no_from_filename(filename: str) -> str | None:
+    """Return the 12-digit register number from the filename, or None if format is invalid."""
+    m = _RESUME_FILENAME_RE.match(filename or "")
+    return m.group(1) if m else None
+
 
 async def upload_and_parse_resume(user_id: str, filename: str, file_content: bytes) -> dict:
-    """Upload resume file, parse with Gemini, extract skills."""
+    """Upload resume file, parse with Gemini, extract skills.
+
+    Filename must match: {12_digit_reg_no}_{name}.{ext}
+    Example: 714023243122_Sajith J.pdf
+    """
     db = get_db()
 
+    # ── Validate filename format ──────────────────────────────────────────────
+    reg_no = extract_reg_no_from_filename(filename)
+    if reg_no is None:
+        raise ValueError(
+            "Invalid filename format. Resume filename must start with your 12-digit register number "
+            "followed by an underscore and your name. "
+            "Example: 714023243122_Sajith J.pdf"
+        )
+
+    # ── Check reg_no uniqueness ───────────────────────────────────────────────
+    # Allow the same user to re-upload (same reg_no), but block if another user already holds it.
+    existing_owner = await db[USERS].find_one(
+        {"reg_no": reg_no, "_id": {"$ne": ObjectId(user_id)}}
+    )
+    if existing_owner:
+        raise ValueError(
+            "This register number is already associated with another account. "
+            "Each student must use their own unique register number."
+        )
+
     # Save file locally
     safe_filename = f"{user_id}_{filename}"
     file_path = os.path.join(settings.UPLOAD_DIR, safe_filename)
@@ -39,6 +75,7 @@ async def upload_and_parse_resume(user_id: str, filename: str, file_content: byt
         "file_path": file_path,
         "parsed_text": parsed_data.get("experience_summary", ""),
         "parsed_data": parsed_data,
+        "reg_no": reg_no,
         "uploaded_at": utc_now(),
     }
 
@@ -48,6 +85,12 @@ async def upload_and_parse_resume(user_id: str, filename: str, file_content: byt
         upsert=True,
     )
 
+    # Persist reg_no on the user document for quick lookup and admin display
+    await db[USERS].update_one(
+        {"_id": ObjectId(user_id)},
+        {"$set": {"reg_no": reg_no}},
+    )
+
     # Upsert skills
     await db[SKILLS].update_one(
         {"user_id": user_id},
@@ -67,6 +110,7 @@ async def upload_and_parse_resume(user_id: str, filename: str, file_content: byt
         "filename": filename,
         "parsed_text": resume_doc["parsed_text"],
         "skills": skills,
+        "reg_no": reg_no,
         "uploaded_at": resume_doc["uploaded_at"],
     }
 

backend/utils/gemini.py

@@ -306,6 +306,50 @@ Return ONLY valid JSON, no markdown formatting."""
         }
 
 
+async def parse_jd_with_gemini(jd_text: str) -> dict:
+    """Extract structured job description data (title, description, required_skills) from raw text."""
+    prompt = f"""You are a job description parser. Extract structured information from the given job description text.
+
+Return ONLY valid JSON with exactly these fields:
+{{
+  "title": "job title (string)",
+  "company": "company name if present, else null",
+  "description": "cleaned full job description text (string)",
+  "required_skills": ["skill1", "skill2", ...]
+}}
+
+Rules:
+1. "title" — infer the most appropriate job title from the content (e.g. "Software Engineer", "Data Analyst").
+2. "company" — extract if explicitly mentioned, otherwise null.
+3. "description" — cleaned, coherent description text; keep it as a single string.
+4. "required_skills" — extract only specific, concrete technical skills, tools, languages, or certifications; no vague traits like "teamwork".
+
+Job Description Text:
+---
+{jd_text}
+---
+
+Return ONLY valid JSON, no markdown."""
+
+    try:
+        raw = await call_gemini(prompt)
+        cleaned = _extract_json_object(raw)
+        parsed = json.loads(cleaned)
+        return {
+            "title": (parsed.get("title") or "").strip() or "Untitled",
+            "company": (parsed.get("company") or "").strip() or None,
+            "description": (parsed.get("description") or "").strip() or jd_text[:2000],
+            "required_skills": normalize_skill_list(parsed.get("required_skills") or []),
+        }
+    except Exception:
+        return {
+            "title": "Untitled",
+            "company": None,
+            "description": jd_text[:2000],
+            "required_skills": [],
+        }
+
+
 async def analyze_resume_vs_job_description(
     role_title: str,
     resume_skills: list,