v2.1

backend/.dockerignore

@@ -0,0 +1,73 @@
+# Environments
+.env
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+venv/
+.venv/
+env/
+.env/
+
+# Distribution / packaging
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Git
+.git/
+.gitignore

backend/Dockerfile

@@ -0,0 +1,24 @@
+# Use the official Python base image
+FROM python:3.10-slim
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy the requirements file into the container
+COPY requirements.txt .
+
+# Install dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application code
+COPY . .
+
+# Expose port 8000
+EXPOSE 8000
+
+# Command to run the application
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/_probe_models.py

@@ -0,0 +1,76 @@
+import asyncio
+import os
+import tempfile
+import time
+
+CANDIDATES = [
+    ("tts_models/en/ljspeech/speedy-speech", None),
+    ("tts_models/en/ljspeech/vits", None),
+    ("tts_models/en/ljspeech/glow-tts", None),
+    ("tts_models/en/ljspeech/tacotron2-DDC", None),
+    ("tts_models/en/ljspeech/fast_pitch", None),
+    ("tts_models/en/vctk/vits", "AUTO_SPEAKERS"),
+    ("tts_models/en/sam/tacotron-DDC", None),
+    ("tts_models/en/blizzard2013/capacitron-t2-c50", None),
+    ("tts_models/en/jenny/jenny", None),
+]
+
+TEST_TEXT = "Hello, this is a short interview voice quality sample."
+
+async def synth_once(tts, speaker=None):
+    fd, path = tempfile.mkstemp(suffix=".wav")
+    os.close(fd)
+    t0 = time.perf_counter()
+    try:
+        kwargs = {"text": TEST_TEXT, "file_path": path}
+        if speaker:
+            kwargs["speaker"] = speaker
+        await asyncio.to_thread(lambda: tts.tts_to_file(**kwargs))
+        elapsed = time.perf_counter() - t0
+        size = os.path.getsize(path)
+        return True, elapsed, size, None
+    except Exception as e:
+        return False, 0.0, 0, str(e)
+    finally:
+        if os.path.exists(path):
+            os.remove(path)
+
+
+async def run():
+    from TTS.api import TTS
+
+    for model_name, speaker_mode in CANDIDATES:
+        print(f"MODEL {model_name}")
+        try:
+            t_load = time.perf_counter()
+            tts = await asyncio.to_thread(lambda: TTS(model_name=model_name, progress_bar=False, gpu=False))
+            print(f"  LOAD_OK {time.perf_counter() - t_load:.2f}s")
+
+            if speaker_mode == "AUTO_SPEAKERS":
+                speakers = list(getattr(tts, "speakers", []) or [])
+                if not speakers:
+                    print("  NO_SPEAKERS_FOUND")
+                    ok, elapsed, size, err = await synth_once(tts)
+                    if ok:
+                        print(f"  SYNTH_OK elapsed={elapsed:.2f}s bytes={size}")
+                    else:
+                        print(f"  SYNTH_FAIL {err}")
+                else:
+                    print(f"  SPEAKER_COUNT {len(speakers)}")
+                    test_speakers = speakers[:12]
+                    for spk in test_speakers:
+                        ok, elapsed, size, err = await synth_once(tts, speaker=spk)
+                        if ok:
+                            print(f"  SPEAKER_OK {spk} elapsed={elapsed:.2f}s bytes={size}")
+                        else:
+                            print(f"  SPEAKER_FAIL {spk} err={err}")
+            else:
+                ok, elapsed, size, err = await synth_once(tts)
+                if ok:
+                    print(f"  SYNTH_OK elapsed={elapsed:.2f}s bytes={size}")
+                else:
+                    print(f"  SYNTH_FAIL {err}")
+        except Exception as e:
+            print(f"  LOAD_FAIL {e}")
+
+asyncio.run(run())

backend/models/collections.py

@@ -4,6 +4,7 @@ USERS = "users"
 RESUMES = "resumes"
 SKILLS = "skills"
 JOB_ROLES = "job_roles"
+JOB_DESCRIPTIONS = "job_descriptions"
 ROLE_REQUIREMENTS = "role_requirements"
 QUESTIONS = "questions"
 TOPICS = "topics"

backend/routers/admin.py

@@ -16,6 +16,12 @@ from services.admin_service import (
     list_quit_interviews, list_admin_reports, get_admin_report_detail,
     list_admin_users, delete_admin_user,
 )
+from services.job_description_service import (
+    create_job_description,
+    list_admin_job_descriptions,
+    update_admin_job_description,
+    delete_admin_job_description,
+)
 from services.analytics_service import get_admin_analytics
 
 router = APIRouter()
@@ -354,6 +360,63 @@ async def get_admin_users(
     return {"items": items}
 
 
+@router.get("/job-descriptions")
+async def get_admin_job_descriptions(
+    owner_user_id: str = Query(None),
+    current_user: dict = Depends(require_role("admin")),
+):
+    """List job descriptions for admin management."""
+    items = await list_admin_job_descriptions(owner_user_id=owner_user_id)
+    return {"items": items}
+
+
+@router.post("/job-descriptions")
+async def create_admin_job_description_endpoint(
+    request_data: dict,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Create a job description as admin."""
+    try:
+        item = await create_job_description(
+            user_id=current_user["user_id"],
+            owner_role="admin",
+            title=request_data.get("title"),
+            company=request_data.get("company"),
+            description=request_data.get("description"),
+            required_skills=request_data.get("required_skills"),
+        )
+        return item
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.put("/job-descriptions/{jd_id}")
+async def update_admin_job_description_endpoint(
+    jd_id: str,
+    request_data: dict,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Update any job description (admin only)."""
+    try:
+        item = await update_admin_job_description(jd_id, request_data)
+        return item
+    except ValueError as e:
+        status_code = 404 if "not found" in str(e).lower() else 400
+        raise HTTPException(status_code=status_code, detail=str(e))
+
+
+@router.delete("/job-descriptions/{jd_id}")
+async def delete_admin_job_description_endpoint(
+    jd_id: str,
+    current_user: dict = Depends(require_role("admin")),
+):
+    """Delete any job description (admin only)."""
+    success = await delete_admin_job_description(jd_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="Job description not found")
+    return {"message": "Job description deleted"}
+
+
 @router.delete("/users/{user_id}")
 async def delete_admin_user_endpoint(
     user_id: str,

backend/routers/interview.py

@@ -2,12 +2,18 @@ from fastapi import APIRouter, Depends, HTTPException
 from auth.jwt import get_current_user
 from schemas.interview import (
     StartInterviewRequest,
+    VerifyResumeJdRequest,
     SubmitAnswerRequest,
     QuitInterviewRequest,
     InterviewStartResponse,
     AnswerResponse,
 )
-from services.interview_service import start_interview, submit_answer, quit_interview
+from services.interview_service import (
+    start_interview,
+    verify_resume_job_description,
+    submit_answer,
+    quit_interview,
+)
 from services.evaluation_service import generate_report
 
 router = APIRouter()
@@ -26,12 +32,33 @@ async def start_interview_endpoint(
             custom_role=request.custom_role,
             interview_type=request.interview_type,
             topic_id=request.topic_id,
+            job_description_id=request.job_description_id,
         )
         return result
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
 
+@router.post("/verify")
+async def verify_resume_job_description_endpoint(
+    request: VerifyResumeJdRequest,
+    current_user: dict = Depends(get_current_user),
+):
+    """Verify resume vs selected job description before starting interview."""
+    try:
+        result = await verify_resume_job_description(
+            user_id=current_user["user_id"],
+            role_id=request.role_id,
+            custom_role=request.custom_role,
+            job_description_id=request.job_description_id,
+        )
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
 @router.post("/answer")
 async def submit_answer_endpoint(
     request: SubmitAnswerRequest,

backend/routers/profile.py

@@ -5,6 +5,12 @@ from models.collections import USERS, RESUMES, SKILLS
 from utils.helpers import str_objectid
 from utils.skills import normalize_skill_list, cluster_skills
 from bson import ObjectId
+from services.job_description_service import (
+    create_job_description,
+    list_my_job_descriptions,
+    update_my_job_description,
+    delete_my_job_description,
+)
 
 router = APIRouter()
 
@@ -107,3 +113,59 @@ async def update_resume_data(
         raise HTTPException(status_code=404, detail="Resume not found. Upload a resume first.")
 
     return {"message": "Resume details updated successfully", "parsed_data": parsed_data}
+
+
+@router.get("/job-descriptions")
+async def get_my_job_descriptions(
+    current_user: dict = Depends(get_current_user),
+):
+    """List current user's job descriptions."""
+    items = await list_my_job_descriptions(current_user["user_id"])
+    return {"items": items}
+
+
+@router.post("/job-descriptions")
+async def create_my_job_description(
+    request_data: dict,
+    current_user: dict = Depends(get_current_user),
+):
+    """Create a new job description for current user."""
+    try:
+        item = await create_job_description(
+            user_id=current_user["user_id"],
+            owner_role=current_user.get("role", "student"),
+            title=request_data.get("title"),
+            company=request_data.get("company"),
+            description=request_data.get("description"),
+            required_skills=request_data.get("required_skills"),
+        )
+        return item
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.put("/job-descriptions/{jd_id}")
+async def update_my_job_description_endpoint(
+    jd_id: str,
+    request_data: dict,
+    current_user: dict = Depends(get_current_user),
+):
+    """Update a current user's job description."""
+    try:
+        item = await update_my_job_description(current_user["user_id"], jd_id, request_data)
+        return item
+    except ValueError as e:
+        status_code = 404 if "not found" in str(e).lower() else 400
+        raise HTTPException(status_code=status_code, detail=str(e))
+
+
+@router.delete("/job-descriptions/{jd_id}")
+async def delete_my_job_description_endpoint(
+    jd_id: str,
+    current_user: dict = Depends(get_current_user),
+):
+    """Delete a current user's job description."""
+    success = await delete_my_job_description(current_user["user_id"], jd_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="Job description not found")
+    return {"message": "Job description deleted"}

backend/schemas/interview.py

@@ -7,6 +7,13 @@ class StartInterviewRequest(BaseModel):
     custom_role: Optional[str] = None
     interview_type: Optional[str] = "resume"
     topic_id: Optional[str] = None
+    job_description_id: Optional[str] = None
+
+
+class VerifyResumeJdRequest(BaseModel):
+    role_id: Optional[str] = None
+    custom_role: Optional[str] = None
+    job_description_id: str
 
 
 class SubmitAnswerRequest(BaseModel):

backend/services/admin_service.py

@@ -3,7 +3,7 @@ import json
 import re
 from datetime import datetime
 from database import get_db
-from models.collections import JOB_ROLES, ROLE_REQUIREMENTS, QUESTIONS, TOPICS, TOPIC_QUESTIONS, SESSIONS, USERS, RESULTS, RESUMES, SKILLS, ANSWERS
+from models.collections import JOB_ROLES, ROLE_REQUIREMENTS, QUESTIONS, TOPICS, TOPIC_QUESTIONS, SESSIONS, USERS, RESULTS, RESUMES, SKILLS, ANSWERS, JOB_DESCRIPTIONS
 from utils.helpers import utc_now, str_objectid, str_objectids
 from utils.gemini import call_gemini
 from utils.resume_text import extract_resume_text
@@ -625,6 +625,7 @@ async def delete_admin_user(target_user_id: str, current_admin_user_id: str) ->
 
     await db[RESUMES].delete_many({"user_id": target_user_id})
     await db[SKILLS].delete_many({"user_id": target_user_id})
+    await db[JOB_DESCRIPTIONS].delete_many({"user_id": target_user_id})
     await db[SESSIONS].delete_many({"user_id": target_user_id})
     await db[ANSWERS].delete_many({"user_id": target_user_id})
     await db[RESULTS].delete_many({"user_id": target_user_id})

backend/services/interview_graph.py

@@ -19,13 +19,11 @@ class InterviewGraphState(TypedDict, total=False):
     question_data: Dict[str, Any]
 
 
-FOUNDATION_QUESTION_LIMIT = 3
+FOUNDATION_QUESTION_LIMIT = 0
 
 
 def _difficulty_for_question_number(question_number: int, foundation_limit: int = FOUNDATION_QUESTION_LIMIT) -> str:
-    if question_number <= foundation_limit:
-        return "easy"
-    if question_number <= foundation_limit + 3:
+    if question_number <= 5:
         return "medium"
     return "hard"
 

backend/services/interview_service.py

@@ -2,11 +2,12 @@ import json
 import asyncio
 from bson import ObjectId
 from database import get_db, get_redis
-from models.collections import SESSIONS, JOB_ROLES, SKILLS, QUESTIONS, TOPICS, TOPIC_QUESTIONS, ROLE_REQUIREMENTS
+from models.collections import SESSIONS, JOB_ROLES, SKILLS, QUESTIONS, TOPICS, TOPIC_QUESTIONS, ROLE_REQUIREMENTS, RESUMES
 from utils.helpers import generate_id, utc_now, str_objectid
 from utils.skills import normalize_skill_list, find_matching_skills, find_missing_skills, build_interview_focus_skills
 from services.interview_graph import run_interview_graph
-from utils.gemini import generate_interview_question_batch
+from utils.gemini import generate_interview_question_batch, analyze_resume_vs_job_description
+from services.job_description_service import get_job_description_for_user
 
 MAX_QUESTIONS = 20
 SESSION_TTL = 7200  # 2 hours
@@ -42,6 +43,15 @@ def _safe_int(value, default: int = 0) -> int:
         return default
 
 
+def _normalize_bank_difficulty(value: str) -> str:
+    difficulty = (value or "medium").strip().lower()
+    if difficulty not in {"easy", "medium", "hard"}:
+        return "medium"
+    if difficulty == "easy":
+        return "medium"
+    return difficulty
+
+
 def _avg_recent_answer_words(qa_pairs: list, window: int = 3) -> int:
     if not qa_pairs:
         return 0
@@ -80,6 +90,68 @@ def _plan_followup_mix(target: int, qa_pairs: list, has_bank_source: bool) -> tu
     return ai_target, bank_target
 
 
+async def _resolve_role_title(db, role_id: str | None, custom_role: str | None) -> str:
+    if custom_role and custom_role.strip():
+        return custom_role.strip()
+
+    if role_id:
+        try:
+            role = await db[JOB_ROLES].find_one({"_id": ObjectId(role_id)})
+            if role:
+                return role["title"]
+        except Exception:
+            # If it's not a valid ObjectId, treat it as a direct generic title.
+            return role_id
+
+    return "Software Developer"
+
+
+async def verify_resume_job_description(
+    user_id: str,
+    role_id: str = None,
+    custom_role: str = None,
+    job_description_id: str = None,
+) -> dict:
+    """Run resume-vs-job-description verification without starting an interview."""
+    if not job_description_id:
+        raise ValueError("job_description_id is required for verification")
+
+    db = get_db()
+
+    resume_doc = await db[RESUMES].find_one({"user_id": user_id})
+    if not resume_doc:
+        raise ValueError("Please upload your resume before running verification")
+
+    skills_doc = await db[SKILLS].find_one({"user_id": user_id})
+    resume_skills = normalize_skill_list(skills_doc.get("skills", [])) if skills_doc else []
+
+    parsed_data = (resume_doc or {}).get("parsed_data", {}) or {}
+    summary_parts = [
+        parsed_data.get("experience_summary") or "",
+        " ".join(parsed_data.get("recommended_roles", []) or []),
+    ]
+    resume_summary = "\n".join([part for part in summary_parts if part]).strip() or "No summary available"
+
+    role_title = await _resolve_role_title(db, role_id=role_id, custom_role=custom_role)
+    selected_jd = await get_job_description_for_user(user_id, job_description_id)
+
+    jd_alignment = await analyze_resume_vs_job_description(
+        role_title=role_title,
+        resume_skills=resume_skills if resume_skills else ["general"],
+        resume_summary=resume_summary,
+        jd_title=selected_jd.get("title", ""),
+        jd_description=selected_jd.get("description", ""),
+        jd_required_skills=selected_jd.get("required_skills", []),
+    )
+
+    return {
+        "role_title": role_title,
+        "job_description": selected_jd,
+        "jd_alignment": jd_alignment,
+        "message": "Verification complete",
+    }
+
+
 async def _get_generated_question_texts(redis, session_id: str) -> list[str]:
     qids = await redis.lrange(f"session:{session_id}:questions", 0, -1)
     questions = []
@@ -113,6 +185,7 @@ async def _generate_question_batch(
             count=target,
             start_question_number=1,
             previous_questions=previous_questions,
+            foundation_limit=0,
         )
         if seeded:
             last = seeded[-1].get("difficulty", current_difficulty)
@@ -178,43 +251,67 @@ async def _fetch_question_bank_batch(
     excluded_questions: list[str],
     limit: int,
 ) -> list[dict]:
-    if not role_id or limit <= 0:
+    if limit <= 0:
         return []
 
-    role_candidates = [role_id]
-    try:
-        oid = ObjectId(role_id)
-        role_candidates.append(str(oid))
-        role_candidates.append(oid)
-    except Exception:
-        pass
-
-    query = {"role_id": {"$in": role_candidates}}
+    query = {"question": {"$exists": True, "$ne": ""}}
+    if role_id:
+        role_candidates = [role_id]
+        try:
+            oid = ObjectId(role_id)
+            role_candidates.append(str(oid))
+            role_candidates.append(oid)
+        except Exception:
+            pass
+        query["role_id"] = {"$in": role_candidates}
 
     excluded = {q.strip().lower() for q in excluded_questions if q}
-    cursor = db[QUESTIONS].find(query).limit(200)
     selected: list[dict] = []
 
-    async for q in cursor:
-        text = (q.get("question") or "").strip()
-        if not text:
-            continue
-        if text.lower() in excluded:
-            continue
-        selected.append(
-            {
-                "question": text,
-                "difficulty": (q.get("difficulty") or "medium").lower(),
-                "category": q.get("category") or "question-bank",
-            }
-        )
-        excluded.add(text.lower())
+    for sample_size in (max(limit * 12, 80), max(limit * 24, 160)):
+        pipeline = [
+            {"$match": query},
+            {"$sample": {"size": sample_size}},
+        ]
+
+        async for q in db[QUESTIONS].aggregate(pipeline):
+            text = (q.get("question") or "").strip()
+            if not text:
+                continue
+            if text.lower() in excluded:
+                continue
+            selected.append(
+                {
+                    "question": text,
+                    "difficulty": _normalize_bank_difficulty(q.get("difficulty") or "medium"),
+                    "category": q.get("category") or "question-bank",
+                }
+            )
+            excluded.add(text.lower())
+            if len(selected) >= limit:
+                break
+
         if len(selected) >= limit:
             break
 
+    # If role-scoped pool is too small, widen to global random pool.
+    if len(selected) < limit and role_id:
+        fallback = await _fetch_question_bank_batch(
+            db=db,
+            role_id=None,
+            excluded_questions=list(excluded),
+            limit=limit - len(selected),
+        )
+        selected.extend(fallback)
+
     return selected
 
 
+def _strict_followup_difficulty(answered_count: int) -> str:
+    # After first DB set (Q1-5), follow-ups should feel like real interview pressure.
+    return "hard" if answered_count >= 10 else "medium"
+
+
 async def _generate_mixed_followup_batch(
     db,
     redis,
@@ -235,15 +332,17 @@ async def _generate_mixed_followup_batch(
 
     previous_questions = await _get_generated_question_texts(redis, session_id)
     qa_pairs = await get_session_qa(session_id)
+    answered_count = len(qa_pairs)
     role_title = session.get("role_title", "Software Developer")
     skills = _safe_json_list(session.get("skills", "[]"))
-    current_difficulty = session.get("current_difficulty", "medium")
+    current_difficulty = _strict_followup_difficulty(answered_count)
 
-    ai_target, bank_target = _plan_followup_mix(
-        target=target,
-        qa_pairs=qa_pairs,
-        has_bank_source=bool(session.get("role_id")),
-    )
+    if target >= 5:
+        ai_target = 3
+        bank_target = 2
+    else:
+        ai_target = min(3, target)
+        bank_target = min(2, max(0, target - ai_target))
 
     from utils.gemini import generate_followup_question_batch_from_qa
 
@@ -487,6 +586,7 @@ async def start_interview(
     custom_role: str = None,
     interview_type: str = "resume",
     topic_id: str = None,
+    job_description_id: str = None,
 ) -> dict:
     """Start a new interview session."""
     interview_type = (interview_type or "resume").strip().lower()
@@ -504,18 +604,7 @@ async def start_interview(
     user_skills = normalize_skill_list(user_skills)
 
     # Get role
-    role_title = "Software Developer"
-    if custom_role:
-        role_title = custom_role
-    elif role_id:
-        from bson import ObjectId
-        try:
-            role = await db[JOB_ROLES].find_one({"_id": ObjectId(role_id)})
-            if role:
-                role_title = role["title"]
-        except Exception:
-            # If it's not a valid ObjectId, assume it's a raw generic title passed from frontend
-            role_title = role_id
+    role_title = await _resolve_role_title(db, role_id=role_id, custom_role=custom_role)
 
     # Compare role requirements with user skills when admin role requirements exist.
     required_skills = []
@@ -527,26 +616,49 @@ async def start_interview(
     matched_role_skills = find_matching_skills(user_skills, required_skills)
     missing_role_skills = find_missing_skills(user_skills, required_skills)
 
+    selected_jd = None
+    if job_description_id:
+        selected_jd = await get_job_description_for_user(user_id, job_description_id)
+
     # Prioritize matched required skills and compress them into cluster-aware focus areas.
     base_skills_for_interview = matched_role_skills if matched_role_skills else user_skills
     skills_for_interview = build_interview_focus_skills(base_skills_for_interview)
     if not skills_for_interview:
         skills_for_interview = ["general"]
 
-    # Workflow: generate first batch upfront, store in Redis, serve Q1.
-    initial_batch, last_difficulty = await _generate_question_batch(
-        role_title=role_title,
-        skills=skills_for_interview,
-        previous_questions=[],
-        generated_count=0,
-        max_questions=MAX_QUESTIONS,
-        current_difficulty="medium",
-        local_summary=None,
-        batch_size=BATCH_SIZE,
+    # First set must come from random DB questions when possible.
+    initial_bank = await _fetch_question_bank_batch(
+        db=db,
+        role_id=role_id,
+        excluded_questions=[],
+        limit=BATCH_SIZE,
     )
+
+    initial_batch = list(initial_bank)
+    initial_ai_items: list[dict] = []
+    if len(initial_batch) < BATCH_SIZE:
+        ai_count = BATCH_SIZE - len(initial_batch)
+        initial_ai_items, _ = await _generate_question_batch(
+            role_title=role_title,
+            skills=skills_for_interview,
+            previous_questions=[q.get("question", "") for q in initial_batch],
+            generated_count=0,
+            max_questions=MAX_QUESTIONS,
+            current_difficulty="medium",
+            local_summary=None,
+            batch_size=ai_count,
+        )
+        initial_batch.extend(initial_ai_items)
+
+    last_difficulty = initial_batch[-1].get("difficulty", "medium") if initial_batch else "medium"
     if not initial_batch:
         raise ValueError("Failed to generate initial interview questions")
 
+    initial_gemini_calls = 1 if initial_ai_items else 0
+    initial_gemini_questions = len(initial_ai_items)
+    initial_bank_questions = len(initial_bank)
+    initial_bank_shortfall = max(0, BATCH_SIZE - len(initial_bank))
+
     session_id = generate_id()
     _LOCAL_SUMMARIES[session_id] = ""
 
@@ -556,15 +668,17 @@ async def start_interview(
         "user_id": user_id,
         "role_id": role_id,
         "role_title": role_title,
+        "job_description_id": selected_jd.get("id") if selected_jd else None,
+        "job_description_title": selected_jd.get("title") if selected_jd else None,
         "status": "in_progress",
         "interview_type": "resume",
         "question_count": 1,
         "max_questions": MAX_QUESTIONS,
         "current_difficulty": initial_batch[0].get("difficulty", "medium"),
-        "metrics_gemini_calls": 1,
-        "metrics_gemini_questions": len(initial_batch),
-        "metrics_bank_questions": 0,
-        "metrics_bank_shortfall": 0,
+        "metrics_gemini_calls": initial_gemini_calls,
+        "metrics_gemini_questions": initial_gemini_questions,
+        "metrics_bank_questions": initial_bank_questions,
+        "metrics_bank_shortfall": initial_bank_shortfall,
         "metrics_generation_batches": 1,
         "started_at": utc_now(),
     }
@@ -588,10 +702,10 @@ async def start_interview(
         "current_difficulty": last_difficulty,
         "interview_type": "resume",
         "status": "in_progress",
-        "metrics_gemini_calls": 1,
-        "metrics_gemini_questions": len(initial_batch),
-        "metrics_bank_questions": 0,
-        "metrics_bank_shortfall": 0,
+        "metrics_gemini_calls": initial_gemini_calls,
+        "metrics_gemini_questions": initial_gemini_questions,
+        "metrics_bank_questions": initial_bank_questions,
+        "metrics_bank_shortfall": initial_bank_shortfall,
         "metrics_generation_batches": 1,
     }
     await redis.hset(f"session:{session_id}", mapping=session_state)
@@ -628,6 +742,8 @@ async def start_interview(
             "seconds": None,
         },
         "message": "Interview started. Good luck!",
+        "job_description": selected_jd,
+        "jd_alignment": None,
     }
 
 

backend/services/job_description_service.py

@@ -0,0 +1,162 @@
+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
+
+
+def _normalize_required_skills(required_skills):
+    items = required_skills or []
+    if not isinstance(items, list):
+        return []
+    seen = set()
+    output = []
+    for raw in items:
+        skill = (raw or "").strip()
+        if not skill:
+            continue
+        key = skill.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        output.append(skill)
+    return output
+
+
+def _build_update_data(data: dict) -> dict:
+    update_data = {}
+    if "title" in data:
+        title = (data.get("title") or "").strip()
+        if not title:
+            raise ValueError("title is required")
+        update_data["title"] = title
+
+    if "company" in data:
+        update_data["company"] = (data.get("company") or "").strip() or None
+
+    if "description" in data:
+        description = (data.get("description") or "").strip()
+        if not description:
+            raise ValueError("description is required")
+        update_data["description"] = description
+
+    if "required_skills" in data:
+        update_data["required_skills"] = _normalize_required_skills(data.get("required_skills"))
+
+    if not update_data:
+        raise ValueError("No fields to update")
+
+    update_data["updated_at"] = utc_now()
+    return update_data
+
+
+async def create_job_description(
+    user_id: str,
+    owner_role: str,
+    title: str,
+    description: str,
+    company: str | None = None,
+    required_skills: list[str] | None = None,
+) -> dict:
+    db = get_db()
+
+    title = (title or "").strip()
+    description = (description or "").strip()
+    if not title:
+        raise ValueError("title is required")
+    if not description:
+        raise ValueError("description is required")
+
+    doc = {
+        "user_id": user_id,
+        "owner_role": owner_role if owner_role in {"student", "admin"} else "student",
+        "title": title,
+        "company": (company or "").strip() or None,
+        "description": description,
+        "required_skills": _normalize_required_skills(required_skills),
+        "created_at": utc_now(),
+        "updated_at": utc_now(),
+    }
+    result = await db[JOB_DESCRIPTIONS].insert_one(doc)
+    doc["_id"] = result.inserted_id
+    return str_objectid(doc)
+
+
+async def list_my_job_descriptions(user_id: str) -> list:
+    db = get_db()
+    docs = await db[JOB_DESCRIPTIONS].find({"user_id": user_id}).sort("updated_at", -1).to_list(length=300)
+    return str_objectids(docs)
+
+
+async def update_my_job_description(user_id: str, jd_id: str, data: dict) -> dict:
+    db = get_db()
+    try:
+        oid = ObjectId(jd_id)
+    except Exception as exc:
+        raise ValueError("Invalid job description id") from exc
+
+    existing = await db[JOB_DESCRIPTIONS].find_one({"_id": oid, "user_id": user_id})
+    if not existing:
+        raise ValueError("Job description not found")
+
+    update_data = _build_update_data(data)
+    await db[JOB_DESCRIPTIONS].update_one({"_id": oid}, {"$set": update_data})
+    updated = await db[JOB_DESCRIPTIONS].find_one({"_id": oid})
+    return str_objectid(updated)
+
+
+async def delete_my_job_description(user_id: str, jd_id: str) -> bool:
+    db = get_db()
+    try:
+        oid = ObjectId(jd_id)
+    except Exception:
+        return False
+    result = await db[JOB_DESCRIPTIONS].delete_one({"_id": oid, "user_id": user_id})
+    return result.deleted_count > 0
+
+
+async def list_admin_job_descriptions(owner_user_id: str | None = None) -> list:
+    db = get_db()
+    query = {"user_id": owner_user_id} if owner_user_id else {}
+    docs = await db[JOB_DESCRIPTIONS].find(query).sort("updated_at", -1).to_list(length=1000)
+    return str_objectids(docs)
+
+
+async def update_admin_job_description(jd_id: str, data: dict) -> dict:
+    db = get_db()
+    try:
+        oid = ObjectId(jd_id)
+    except Exception as exc:
+        raise ValueError("Invalid job description id") from exc
+
+    existing = await db[JOB_DESCRIPTIONS].find_one({"_id": oid})
+    if not existing:
+        raise ValueError("Job description not found")
+
+    update_data = _build_update_data(data)
+    await db[JOB_DESCRIPTIONS].update_one({"_id": oid}, {"$set": update_data})
+    updated = await db[JOB_DESCRIPTIONS].find_one({"_id": oid})
+    return str_objectid(updated)
+
+
+async def delete_admin_job_description(jd_id: str) -> bool:
+    db = get_db()
+    try:
+        oid = ObjectId(jd_id)
+    except Exception:
+        return False
+    result = await db[JOB_DESCRIPTIONS].delete_one({"_id": oid})
+    return result.deleted_count > 0
+
+
+async def get_job_description_for_user(user_id: str, jd_id: str) -> dict:
+    db = get_db()
+    try:
+        oid = ObjectId(jd_id)
+    except Exception as exc:
+        raise ValueError("Invalid job description id") from exc
+
+    doc = await db[JOB_DESCRIPTIONS].find_one({"_id": oid, "user_id": user_id})
+    if not doc:
+        raise ValueError("Job description not found")
+    return str_objectid(doc)

backend/utils/gemini.py

@@ -1,6 +1,7 @@
 from google import genai
 from config import get_settings
 from utils.skills import normalize_skill_list
+import asyncio
 import json
 import re
 from langchain_core.prompts import PromptTemplate
@@ -10,6 +11,20 @@ settings = get_settings()
 client = genai.Client(api_key=settings.GEMINI_API_KEY)
 
 
+def _is_transient_gemini_error(error: Exception) -> bool:
+    message = str(error or "").lower()
+    transient_markers = [
+        "503",
+        "unavailable",
+        "resource_exhausted",
+        "high demand",
+        "deadline",
+        "timed out",
+        "timeout",
+    ]
+    return any(marker in message for marker in transient_markers)
+
+
 async def call_gemini(prompt: str, system_instruction: str = None) -> str:
     """Call Gemini API with a prompt and optional system instruction."""
     config = {}
@@ -17,12 +32,24 @@ async def call_gemini(prompt: str, system_instruction: str = None) -> str:
         config["system_instruction"] = system_instruction
     config["response_mime_type"] = "application/json"
 
-    response = client.models.generate_content(
-        model=settings.GEMINI_MODEL,
-        contents=prompt,
-        config=config if config else None,
-    )
-    return response.text
+    last_error = None
+    max_attempts = 3
+    for attempt in range(max_attempts):
+        try:
+            response = client.models.generate_content(
+                model=settings.GEMINI_MODEL,
+                contents=prompt,
+                config=config if config else None,
+            )
+            return (response.text or "").strip()
+        except Exception as exc:
+            last_error = exc
+            if _is_transient_gemini_error(exc) and attempt < max_attempts - 1:
+                await asyncio.sleep(0.8 * (attempt + 1))
+                continue
+            break
+
+    raise RuntimeError(f"Gemini request failed: {last_error}")
 
 
 def _extract_json_object(text: str) -> str:
@@ -61,6 +88,44 @@ def _fallback_skill_scan(resume_text: str) -> list:
     return normalize_skill_list(found)
 
 
+def _is_loose_answer(answer: str) -> bool:
+    text = (answer or "").strip().lower()
+    if not text:
+        return True
+
+    word_count = len(text.split())
+    if word_count < 18:
+        return True
+
+    weak_markers = [
+        "i think",
+        "maybe",
+        "not sure",
+        "dont know",
+        "don't know",
+        "something like",
+        "etc",
+        "kind of",
+        "sort of",
+    ]
+    return any(marker in text for marker in weak_markers)
+
+
+def _collect_loose_qa(qa_pairs: list, limit: int = 4) -> list:
+    loose = []
+    for qa in reversed(qa_pairs or []):
+        question = (qa or {}).get("question", "")
+        answer = (qa or {}).get("answer", "")
+        if not question or not answer:
+            continue
+        if _is_loose_answer(answer):
+            loose.append({"question": question, "answer": answer})
+        if len(loose) >= limit:
+            break
+    loose.reverse()
+    return loose
+
+
 async def parse_resume_with_gemini(resume_text: str) -> dict:
     """Parse resume text and extract structured data using Gemini."""
     prompt = f"""Analyze the following resume and extract structured information.
@@ -89,8 +154,22 @@ Resume text:
 
 Return ONLY valid JSON, no markdown formatting."""
 
-    result = await call_gemini(prompt)
-    result = _extract_json_object(result)
+    try:
+        result = await call_gemini(prompt)
+        result = _extract_json_object(result)
+    except Exception:
+        return {
+            "name": None,
+            "email": None,
+            "phone": None,
+            "location": None,
+            "skills": _fallback_skill_scan(resume_text),
+            "recommended_roles": [],
+            "experience_summary": "Unable to parse with AI right now. Please retry.",
+            "experience": [],
+            "education": [],
+            "projects": [],
+        }
 
     try:
         parsed = json.loads(result)
@@ -123,6 +202,75 @@ Return ONLY valid JSON, no markdown formatting."""
         }
 
 
+async def analyze_resume_vs_job_description(
+    role_title: str,
+    resume_skills: list,
+    resume_summary: str,
+    jd_title: str,
+    jd_description: str,
+    jd_required_skills: list | None = None,
+) -> dict:
+    """Compare resume and job description to produce interview guidance."""
+    jd_required_skills = jd_required_skills or []
+    prompt = f"""You are an interview coach helping a student prepare for a job.
+
+Role title: {role_title}
+Job Description Title: {jd_title}
+Job Description Text:
+---
+{jd_description}
+---
+
+Job Description Required Skills (if provided): {json.dumps(jd_required_skills)}
+
+Student Resume Skills: {json.dumps(resume_skills)}
+Student Resume Summary:
+---
+{resume_summary}
+---
+
+Return ONLY valid JSON with this structure:
+{{
+  "meeting_expectations": ["..."],
+  "missing_expectations": ["..."],
+  "improvement_suggestions": ["..."],
+  "fit_summary": "short summary"
+}}
+
+Rules:
+1) Be practical and concise.
+2) Mention what already matches first.
+3) Missing expectations should be specific and skill/experience-oriented.
+4) Suggestions should be actionable and student-friendly.
+5) Avoid harsh wording.
+"""
+
+    try:
+        result = _extract_json_object(await call_gemini(prompt))
+        parsed = json.loads(result)
+        return {
+            "meeting_expectations": parsed.get("meeting_expectations", [])[:10],
+            "missing_expectations": parsed.get("missing_expectations", [])[:10],
+            "improvement_suggestions": parsed.get("improvement_suggestions", [])[:10],
+            "fit_summary": parsed.get("fit_summary", ""),
+        }
+    except Exception:
+        resume_set = {s.lower() for s in normalize_skill_list(resume_skills)}
+        required = normalize_skill_list(jd_required_skills)
+        missing = [s for s in required if s.lower() not in resume_set]
+        met = [s for s in required if s.lower() in resume_set]
+        return {
+            "meeting_expectations": met[:6],
+            "missing_expectations": missing[:6],
+            "improvement_suggestions": [
+                "Build 1-2 focused projects aligned with missing JD skills.",
+                "Use STAR-style examples for your strongest matching skills.",
+                "Revise resume bullets to highlight measurable impact.",
+            ],
+            "fit_summary": "You match some expectations and can improve fit by addressing the missing skills.",
+        }
+
+
 async def generate_interview_question(
     skills: list,
     role_title: str,
@@ -169,10 +317,10 @@ Return ONLY valid JSON, no markdown formatting."""
     )
     prompt = prompt_template.format(context=context, difficulty=difficulty)
 
-    result = _extract_json_object(await call_gemini(prompt))
     try:
+        result = _extract_json_object(await call_gemini(prompt))
         return json.loads(result)
-    except json.JSONDecodeError:
+    except Exception:
         return {
             "question": f"Tell me about your experience with {skills[0] if skills else 'software development'}.",
             "difficulty": difficulty,
@@ -235,8 +383,8 @@ Return ONLY JSON, no markdown."""
     )
     prompt = prompt_template.format(context=context, count=count)
 
-    result = (await call_gemini(prompt)).strip()
     try:
+        result = (await call_gemini(prompt)).strip()
         data = json.loads(result)
         if not isinstance(data, list):
             raise ValueError("Batch response is not a list")
@@ -302,21 +450,24 @@ async def generate_followup_question_batch_from_qa(
         "difficulty": difficulty,
         "count": count,
         "answered_qa": compact_qa,
+        "loose_qa": _collect_loose_qa(qa_pairs),
         "previous_questions": previous_questions,
     }
 
     prompt_template = PromptTemplate.from_template(
-        """You are generating technical interview follow-up questions.
+        """You are generating strict, concept-focused technical interview follow-up questions.
 
 Input JSON:
 {payload}
 
 Instructions:
 1. Generate exactly {count} follow-up questions using answered_qa context.
-2. Questions must continue naturally from candidate's previous answers.
+    2. Questions must continue naturally from candidate's previous answers.
 3. Do not repeat or paraphrase any question in previous_questions.
-4. Keep questions practical and role-relevant.
-5. Use difficulty {difficulty}.
+    4. Prioritize loose_qa first: if any answer is vague/short/uncertain, ask a direct follow-up that probes missing concept depth.
+    5. Focus on concept validation (why, how, trade-offs, failure modes), not memorized definitions.
+    6. Keep questions practical and role-relevant.
+    7. Use difficulty {difficulty}. Do not output easy/basic-level questions.
 
 Return ONLY valid JSON array with objects:
 - "question": string
@@ -331,8 +482,8 @@ No markdown, no extra text."""
         difficulty=difficulty,
     )
 
-    result = (await call_gemini(prompt)).strip()
     try:
+        result = (await call_gemini(prompt)).strip()
         data = json.loads(result)
         if not isinstance(data, list):
             raise ValueError("Follow-up batch response is not a list")
@@ -377,20 +528,25 @@ async def evaluate_interview(questions_and_answers: list, role_title: str) -> di
     for i, qa in enumerate(questions_and_answers, 1):
         qa_text += f"\nQ{i}: {qa['question']}\nA{i}: {qa['answer']}\n"
 
-        prompt_template = PromptTemplate.from_template(
-                """You are an interview coach for college students evaluating a candidate for the role: {role_title}
+    prompt_template = PromptTemplate.from_template(
+                """You are a strict technical interviewer evaluating a candidate for the role: {role_title}.
 
 Here are the interview questions and the candidate's answers:
 {qa_text}
 
-Evaluation style requirements:
-1. Evaluate based on concept understanding (not perfection), effort, and clarity.
-2. If an answer is incomplete:
-     - acknowledge what is correct,
-     - gently point out what is missing,
-     - give a hint instead of giving the full direct answer.
-3. Avoid harsh, discouraging, or overly critical language.
-4. Keep feedback constructive, encouraging, and learning-oriented.
+Scoring policy (concept-first, strict):
+1. Score primarily on conceptual correctness, depth, and reasoning quality.
+2. Do NOT reward answer length, confidence, or communication style when concepts are wrong.
+3. Penalize vague, hand-wavy, or uncertain answers.
+4. Penalize technically incorrect claims even if explanation sounds fluent.
+5. Reward precise mechanisms, trade-offs, edge cases, and debugging logic.
+
+Score rubric per answer:
+- 90-100: conceptually correct, deep, and accurate with strong reasoning
+- 70-89: mostly correct with minor conceptual gaps
+- 50-69: partially correct but misses key mechanisms
+- 30-49: shallow/vague with major conceptual gaps
+- 0-29: incorrect or off-topic
 
 Return a JSON object with:
 - "overall_score": integer from 0-100
@@ -398,19 +554,19 @@ Return a JSON object with:
     - "question": the question text
     - "answer": the answer text
     - "score": integer 0-100
-    - "feedback": specific but supportive coaching feedback for this answer
+    - "feedback": concise concept-focused feedback for this answer
 - "strengths": list of 3-5 strength areas
-- "weaknesses": list of 3-5 areas for improvement (worded supportively)
-- "recommendations": list of 3-5 actionable learning recommendations
+- "weaknesses": list of 3-5 concept gaps
+- "recommendations": list of 3-5 actionable concept-improvement recommendations
 
 Return ONLY valid JSON, no markdown formatting."""
         )
     prompt = prompt_template.format(role_title=role_title, qa_text=qa_text)
 
-    result = _extract_json_object(await call_gemini(prompt))
     try:
+        result = _extract_json_object(await call_gemini(prompt))
         return json.loads(result)
-    except json.JSONDecodeError:
+    except Exception:
         return {
             "overall_score": 50,
             "detailed_scores": [],