EvalBot v2: interview analysis, practice mode, English/Arabic reports

.dockerignore

@@ -0,0 +1,6 @@
+.git
+__pycache__
+processed_audio
+temp_files
+static/outputs
+models

.gitattributes

@@ -0,0 +1,4 @@
+assets/fonts/Amiri-Bold.ttf filter=lfs diff=lfs merge=lfs -text
+assets/fonts/Amiri-Regular.ttf filter=lfs diff=lfs merge=lfs -text
+assets/sample_interview.mp3 filter=lfs diff=lfs merge=lfs -text
+assets/models/role_classifier.joblib filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+static/outputs/
+processed_audio/
+temp_files/
+models/
+.env
+interview_transcripts_by_turkers.csv
+*.avi

Dockerfile

@@ -0,0 +1,34 @@
+FROM python:3.10-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ffmpeg libsndfile1 sox curl build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 appuser
+WORKDIR /app
+RUN mkdir -p /app/temp_files /app/processed_audio /app/models /app/static/outputs /tmp/matplotlib \
+    && chown -R appuser:appuser /app /tmp/matplotlib
+
+ENV MPLCONFIGDIR=/tmp/matplotlib \
+    HF_HOME=/app/.cache/huggingface \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+USER appuser
+ENV PATH="/home/appuser/.local/bin:${PATH}"
+
+COPY --chown=appuser:appuser requirements.txt .
+RUN pip install --user --upgrade pip \
+    && pip install --user "Cython==0.29.36" "setuptools<70" wheel \
+    && pip install --user --no-build-isolation "youtokentome==1.0.6" \
+    && pip install --user -r requirements.txt
+
+COPY --chown=appuser:appuser . .
+
+# Train the role classifier and download the speaker model at build time,
+# so the Space is ready as soon as it starts
+RUN python -c "import process_interview as p; p.get_role_classifier(); p._get_speaker_model()"
+
+EXPOSE 7860
+HEALTHCHECK --interval=30s --timeout=10s CMD curl -f http://localhost:7860/health || exit 1
+CMD ["python", "-m", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,100 @@
+---
+title: EvalBot - Interview Analysis System
+emoji: 🎤
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+short_description: AI interview analysis and practice coach (English/Arabic)
+---
+
+# EvalBot: Interview Audio Analysis
+
+Two ways to use it:
+
+- **Analyze an interview:** upload a recorded job interview (or try the built-in sample) and get a full candidate evaluation: who said what, how the candidate sounded, a score and feedback for every question, and an AI-written assessment. Results appear on the page with a transcript synced to the audio, and as a PDF report and JSON.
+- **Practice mode:** pick a question (or generate questions for any job title), listen to it, record your answer with the microphone, and get instant feedback: a score, what went well, what to improve, a delivery tip, and a stronger version of your answer.
+
+The interface and the reports are available in **English and Arabic** (the Arabic PDF is fully right-to-left).
+
+Part of **EvalBot**, a graduation project at the Faculty of Computers and Artificial Intelligence, Benha University. Backend API: [nourhan-shalaby/EvalBot-Backend-API](https://github.com/nourhan-shalaby/EvalBot-Backend-API).
+
+## Pipeline
+
+| Step | What happens | Tools |
+|---|---|---|
+| 1. Conversion | Any audio/video file to 16 kHz mono WAV | ffmpeg |
+| 2. Transcription | Speech-to-text with speaker diarization (filler words kept) | AssemblyAI |
+| 3. Prosody | Pitch and intensity per utterance | librosa |
+| 4. Speaker identification | One voice embedding per speaker, matched by cosine similarity against or enrolled into a vector index, so returning speakers are recognized | NVIDIA NeMo TitaNet; Pinecone, or a built-in NumPy vector index when Pinecone isn't configured |
+| 5. Role classification | Decides which speaker is the interviewer and which is the candidate | Random Forest (TF-IDF + handcrafted features) trained on ~3,000 labeled utterances from the MIT Interview dataset; ~92% utterance accuracy on held-out interviews, aggregated per speaker |
+| 6. Voice analysis | Speaking rate, filler words, repetition, pitch, jitter/shimmer, and confidence, anxiety and hesitation scores | librosa, NumPy |
+| 7. Question pairing | Groups the transcript into question/answer pairs | Python |
+| 8. Evaluation | Structured assessment: per-question score, what went well, what to improve and a stronger answer; summary, strengths with evidence, development areas, role fit, recommendations, next steps, content score. In English or Arabic | Gemini (JSON schema output) |
+| 9. Report | Multi-page PDF (English, or right-to-left Arabic) with tables, charts, per-question feedback and an annotated transcript, plus a JSON export | ReportLab, Matplotlib, arabic-reshaper, python-bidi |
+
+The **suitability score** (0-100) combines answer content (60%, from the AI evaluation) and vocal delivery (40%). If the AI evaluation is unavailable, the report is marked as provisional and based on voice only.
+
+## API
+
+### `POST /process-audio`
+Form fields: `user_id`, either `file` (upload) or `file_url`, and optionally `lang` (`en` or `ar`).
+
+```bash
+curl -X POST https://evalbot-audio-evalbot.hf.space/process-audio \
+  -F user_id=candidate_42 \
+  -F file=@interview.mp3
+```
+
+```json
+{
+  "user_id": "candidate_42",
+  "suitability_score": 81.3,
+  "verdict": "Outstanding candidate, recommended for advancement.",
+  "summary": "...",
+  "pdf_url": "https://evalbot-audio-evalbot.hf.space/static/outputs/pdf/candidate_42_..._report.pdf",
+  "json_url": "https://evalbot-audio-evalbot.hf.space/static/outputs/json/candidate_42_..._analysis.json"
+}
+```
+
+### Background jobs (used by the web page)
+- `POST /jobs` (same form fields, or `sample=true` for the demo interview) returns `{"job_id": "..."}`
+- `GET /jobs/{job_id}` returns status, the current step and, when done, the result
+
+### Practice mode
+- `GET /practice/questions`: built-in question bank (General, Behavioral, Data Engineering, Software Engineering, AI / Machine Learning)
+- `POST /practice/generate` (form field `role`): five AI-generated questions for a job title
+- `POST /practice` (form fields `question`, `file`, optional `lang` and `role`): evaluates one recorded answer and returns the transcript, voice metrics and feedback, usually in 10-20 seconds
+
+### `GET /health`
+Shows which external services are configured.
+
+## Configuration
+
+Set these as **Secrets** in the Space settings. Never put keys in the code.
+
+| Secret | Required | Used for |
+|---|---|---|
+| `ASSEMBLYAI_API_KEY` (or `ASSEMBLYAI_KEY`) | yes | Transcription and diarization |
+| `GEMINI_API_KEY` | recommended | AI evaluation (without it, the report covers voice metrics only) |
+| `PINECONE_API_KEY` | optional | Use Pinecone for speaker identification. Without it, a built-in vector index is used (saved to `/data` if the Space has persistent storage, otherwise reset on restart) |
+
+Optional variables: `GEMINI_MODEL` (default `gemini-3.5-flash-lite`, with automatic fallback to other Flash models if it is slow or unavailable), `GEMINI_TIMEOUT_S` (default 60), `PINECONE_INDEX`, `BASE_URL`, `MAX_UPLOAD_MB`.
+
+## Run locally
+
+```bash
+docker build -t evalbot-audio .
+docker run -p 7860:7860 -e ASSEMBLYAI_API_KEY=... -e GEMINI_API_KEY=... -e PINECONE_API_KEY=... evalbot-audio
+# open http://localhost:7860
+```
+
+Or without Docker: `python process_interview.py interview.mp3 candidate_42`.
+
+## Notes and limitations
+- Interviews and practice answers should be in English (the feedback and report can be in Arabic).
+- Interviews with two speakers work best.
+- The sample interview was generated with text-to-speech (Piper voices) for demonstration.
+- The confidence, anxiety and hesitation scores are heuristics computed from the voice signal. They support a human reviewer and are not a hiring decision.
+- The Space runs on free CPU hardware and sleeps when idle; the first request after a pause takes a minute to wake it up.

app.py

@@ -0,0 +1,253 @@
+"""EvalBot audio analysis service (FastAPI).
+
+Endpoints
+  GET  /                      Web demo: upload an interview recording and get the report
+  GET  /health                Health check (also reports which services are configured)
+  POST /process-audio         Synchronous API used by the EvalBot backend/mobile app
+  POST /jobs                  Start an analysis in the background (used by the web demo; sample=true uses the demo interview)
+  GET  /jobs/{job_id}         Poll job status / result
+  GET  /practice/questions    Built-in practice question bank
+  POST /practice/generate     AI-generated questions for a given role
+  POST /practice              Evaluate one recorded answer to one question (instant feedback)
+  GET  /sample.mp3            The demo interview recording
+  GET  /static/outputs/pdf/{filename}, /static/outputs/json/{filename}   Download reports
+"""
+import logging
+import os
+import re
+import shutil
+import threading
+import time
+import uuid
+from typing import Dict, Optional
+
+import requests
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+from fastapi.responses import FileResponse, HTMLResponse
+from pydantic import BaseModel
+
+import process_interview as pipeline
+
+logger = logging.getLogger("evalbot.app")
+
+TEMP_DIR = "./temp_files"
+OUTPUT_DIR = "./static/outputs"
+JSON_DIR = os.path.join(OUTPUT_DIR, "json")
+PDF_DIR = os.path.join(OUTPUT_DIR, "pdf")
+for d in (TEMP_DIR, JSON_DIR, PDF_DIR):
+    os.makedirs(d, exist_ok=True)
+
+BASE_URL = os.getenv("BASE_URL", "https://evalbot-audio-evalbot.hf.space").rstrip("/")
+MAX_UPLOAD_MB = int(os.getenv("MAX_UPLOAD_MB", "100"))
+ALLOWED_EXT = {".wav", ".mp3", ".m4a", ".flac", ".ogg", ".webm", ".mp4", ".aac", ".opus"}
+
+app = FastAPI(title="EvalBot Audio Analysis", version="2.0")
+_jobs: Dict[str, Dict] = {}
+_job_lock = threading.Lock()
+_pipeline_lock = threading.Semaphore(int(os.getenv("MAX_CONCURRENT_JOBS", "1")))
+
+
+@app.on_event("startup")
+def warm_up():
+    threading.Thread(target=pipeline.load_models, daemon=True).start()
+
+
+SAMPLE_AUDIO = os.path.join(os.path.dirname(os.path.abspath(__file__)), "assets", "sample_interview.mp3")
+
+
+class ProcessResponse(BaseModel):
+    user_id: str
+    summary: str
+    suitability_score: float
+    verdict: str
+    json_url: str
+    pdf_url: str
+
+
+def _safe_id(value: str) -> str:
+    cleaned = re.sub(r"[^A-Za-z0-9_-]", "_", value or "candidate")[:40]
+    return cleaned or "candidate"
+
+
+def _save_input(user_id: str, file_url: Optional[str], file: Optional[UploadFile]) -> str:
+    suffix = ".audio"
+    if file is not None and file.filename:
+        suffix = os.path.splitext(file.filename)[1].lower() or suffix
+        if suffix not in ALLOWED_EXT:
+            raise HTTPException(400, f"Unsupported file type {suffix}. Use one of: {', '.join(sorted(ALLOWED_EXT))}")
+    local_path = os.path.join(TEMP_DIR, f"{user_id}_{uuid.uuid4().hex}{suffix}")
+    limit = MAX_UPLOAD_MB * 1024 * 1024
+    written = 0
+    try:
+        if file_url:
+            with requests.get(file_url, stream=True, timeout=60) as resp:
+                if resp.status_code != 200:
+                    raise HTTPException(400, "Could not download the audio from the provided URL.")
+                with open(local_path, "wb") as out:
+                    for chunk in resp.iter_content(1024 * 1024):
+                        written += len(chunk)
+                        if written > limit:
+                            raise HTTPException(413, f"File is larger than {MAX_UPLOAD_MB} MB.")
+                        out.write(chunk)
+        elif file is not None:
+            with open(local_path, "wb") as out:
+                while chunk := file.file.read(1024 * 1024):
+                    written += len(chunk)
+                    if written > limit:
+                        raise HTTPException(413, f"File is larger than {MAX_UPLOAD_MB} MB.")
+                    out.write(chunk)
+        else:
+            raise HTTPException(400, "Provide an audio file or a file_url.")
+    except Exception:
+        if os.path.exists(local_path):
+            os.remove(local_path)
+        raise
+    return local_path
+
+
+def _lang(value: Optional[str]) -> str:
+    return "ar" if (value or "").lower().startswith("ar") else "en"
+
+
+def _copy_sample(user_id: str) -> str:
+    local_path = os.path.join(TEMP_DIR, f"{user_id}_{uuid.uuid4().hex}.mp3")
+    shutil.copy(SAMPLE_AUDIO, local_path)
+    return local_path
+
+
+def _run(local_path: str, user_id: str, progress=None, lang: str = "en") -> Dict:
+    with _pipeline_lock:
+        try:
+            result = pipeline.process_interview(local_path, user_id=user_id, progress=progress, lang=lang)
+        finally:
+            if os.path.exists(local_path):
+                os.remove(local_path)
+    pdf_name = os.path.basename(result["pdf_path"])
+    json_name = os.path.basename(result["json_path"])
+    shutil.move(result["pdf_path"], os.path.join(PDF_DIR, pdf_name))
+    shutil.move(result["json_path"], os.path.join(JSON_DIR, json_name))
+    return {
+        "user_id": user_id,
+        "summary": " ".join(result["summary"]) if result["summary"] else "Interview analyzed successfully.",
+        "executive_summary": result["summary"],
+        "suitability_score": result["suitability_score"],
+        "verdict": result["verdict"],
+        "voice": result["voice"],
+        "pdf_url": f"{BASE_URL}/static/outputs/pdf/{pdf_name}",
+        "json_url": f"{BASE_URL}/static/outputs/json/{json_name}",
+        "pdf_path": f"/static/outputs/pdf/{pdf_name}",
+        "json_path": f"/static/outputs/json/{json_name}",
+        "lang": result["lang"],
+    }
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "services": pipeline.validate_env_vars()}
+
+
+@app.post("/process-audio", response_model=ProcessResponse)
+def process_audio(user_id: str = Form(...), file_url: Optional[str] = Form(None),
+                  file: Optional[UploadFile] = File(None), lang: str = Form("en")):
+    user_id = _safe_id(user_id)
+    local_path = _save_input(user_id, file_url, file)
+    try:
+        return _run(local_path, user_id, lang=_lang(lang))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception("Processing failed")
+        raise HTTPException(500, f"Processing failed: {e}")
+
+
+@app.post("/jobs")
+def create_job(user_id: str = Form("candidate"), file_url: Optional[str] = Form(None),
+               file: Optional[UploadFile] = File(None), lang: str = Form("en"), sample: bool = Form(False)):
+    user_id = _safe_id(user_id)
+    lang = _lang(lang)
+    local_path = _copy_sample(user_id) if sample else _save_input(user_id, file_url, file)
+    job_id = uuid.uuid4().hex
+    with _job_lock:
+        _jobs[job_id] = {"status": "queued", "step": "Waiting to start", "created": time.time()}
+
+    def progress(msg):
+        with _job_lock:
+            _jobs[job_id].update(status="running", step=msg)
+
+    def worker():
+        try:
+            result = _run(local_path, user_id, progress, lang)
+            with _job_lock:
+                _jobs[job_id].update(status="done", step="Done", result=result)
+        except Exception as e:
+            logger.exception("Job %s failed", job_id)
+            with _job_lock:
+                _jobs[job_id].update(status="error", step="Failed", error=str(e))
+
+    threading.Thread(target=worker, daemon=True).start()
+    return {"job_id": job_id}
+
+
+@app.get("/jobs/{job_id}")
+def get_job(job_id: str):
+    job = _jobs.get(job_id)
+    if not job:
+        raise HTTPException(404, "Job not found")
+    return job
+
+
+@app.get("/sample.mp3")
+def sample_audio():
+    return FileResponse(SAMPLE_AUDIO, media_type="audio/mpeg")
+
+
+@app.get("/practice/questions")
+def practice_questions():
+    return pipeline.QUESTION_BANK
+
+
+@app.post("/practice/generate")
+def practice_generate(role: str = Form(...)):
+    questions = pipeline.generate_practice_questions(role)
+    if not questions:
+        raise HTTPException(503, "Could not generate questions right now. Try one of the built-in categories.")
+    return {"role": role, "questions": questions}
+
+
+@app.post("/practice")
+def practice(question: str = Form(...), file: UploadFile = File(...), lang: str = Form("en"),
+             role: str = Form("")):
+    if not question.strip():
+        raise HTTPException(400, "Missing question")
+    if file.filename and "." not in file.filename:
+        file.filename += ".webm"
+    local_path = _save_input("practice", None, file)
+    try:
+        with _pipeline_lock:
+            return pipeline.evaluate_practice_answer(local_path, question.strip()[:500], _lang(lang), role.strip()[:80])
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+    except Exception as e:
+        logger.exception("Practice evaluation failed")
+        raise HTTPException(500, f"Could not evaluate the answer: {e}")
+    finally:
+        if os.path.exists(local_path):
+            os.remove(local_path)
+
+
+@app.get("/static/outputs/{kind}/{filename}")
+def get_output(kind: str, filename: str):
+    if kind not in ("pdf", "json"):
+        raise HTTPException(404)
+    safe = os.path.basename(filename)
+    path = os.path.join(PDF_DIR if kind == "pdf" else JSON_DIR, safe)
+    if not os.path.isfile(path):
+        raise HTTPException(404, "File not found")
+    return FileResponse(path, media_type="application/pdf" if kind == "pdf" else "application/json",
+                        filename=safe)
+
+
+@app.get("/", response_class=HTMLResponse)
+def index():
+    with open(os.path.join(os.path.dirname(__file__), "static_ui.html"), encoding="utf-8") as f:
+        return f.read()

assets/fonts/Amiri-Bold.ttf

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

assets/fonts/Amiri-Regular.ttf

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

assets/fonts/LICENSE-Amiri.txt

@@ -0,0 +1,4 @@
+Amiri font (Amiri-Regular.ttf, Amiri-Bold.ttf)
+Copyright (c) 2010-2022 Khaled Hosny <khaledhosny@eglug.org>
+Licensed under the SIL Open Font License, Version 1.1 (https://openfontlicense.org).
+Used to render Arabic text in EvalBot PDF reports.

assets/models/role_classifier.joblib

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

assets/sample_interview.mp3

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

process_interview.py

@@ -0,0 +1,1540 @@
+"""EvalBot audio analysis pipeline.
+
+Recorded interview in -> PDF + JSON candidate report out.
+
+Steps:
+  1. Convert any audio/video to 16 kHz mono WAV (ffmpeg)
+  2. Transcribe with speaker diarization (AssemblyAI)
+  3. Extract prosodic features per utterance (librosa)
+  4. Identify speakers with NVIDIA NeMo TitaNet embeddings + Pinecone vector index
+  5. Classify each speaker as Interviewer / Interviewee (Random Forest trained on
+     the labeled MIT interview transcripts)
+  6. Analyze the interviewee's voice (rate, fillers, repetition, pitch, intensity,
+     confidence / anxiety / hesitation)
+  7. Generate a structured evaluation with Gemini
+  8. Render a multi-page PDF report and a JSON export
+"""
+import csv
+import io
+import json
+import logging
+import os
+import re
+import subprocess
+import threading
+import time
+import uuid
+from typing import Dict, List, Optional
+from xml.sax.saxutils import escape
+
+import joblib
+import librosa
+import numpy as np
+import requests
+import soundfile as sf
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt  # noqa: E402
+from reportlab.lib import colors  # noqa: E402
+from reportlab.lib.pagesizes import letter  # noqa: E402
+from reportlab.lib.styles import ParagraphStyle  # noqa: E402
+from reportlab.lib.units import inch  # noqa: E402
+from reportlab.platypus import (  # noqa: E402
+    Image, KeepTogether, PageBreak, Paragraph, SimpleDocTemplate, Spacer, Table, TableStyle,
+)
+from sklearn.ensemble import RandomForestClassifier  # noqa: E402
+from sklearn.feature_extraction.text import TfidfVectorizer  # noqa: E402
+from sklearn.model_selection import GroupShuffleSplit  # noqa: E402
+from sklearn.pipeline import FeatureUnion, Pipeline  # noqa: E402
+from sklearn.preprocessing import FunctionTransformer  # noqa: E402
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+logger = logging.getLogger("evalbot")
+logging.getLogger("nemo_logger").setLevel(logging.ERROR)
+logging.getLogger("nemo").setLevel(logging.ERROR)
+
+# --------------------------------------------------------------------------------------
+# Configuration (all secrets come from environment variables / Space secrets)
+# --------------------------------------------------------------------------------------
+OUTPUT_DIR = os.getenv("EVALBOT_WORK_DIR", "./processed_audio")
+MODEL_DIR = os.getenv("EVALBOT_MODEL_DIR", "./models")
+TRAINING_CSV = os.getenv("EVALBOT_TRAINING_CSV", "interview_transcripts_by_turkers.csv")
+os.makedirs(OUTPUT_DIR, exist_ok=True)
+os.makedirs(MODEL_DIR, exist_ok=True)
+
+ASSEMBLYAI_API_KEY = os.getenv("ASSEMBLYAI_API_KEY") or os.getenv("ASSEMBLYAI_KEY")
+PINECONE_API_KEY = os.getenv("PINECONE_API_KEY")
+GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
+GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.5-flash-lite")
+GEMINI_TIMEOUT_S = int(os.getenv("GEMINI_TIMEOUT_S", "60"))
+# Tried in order if the configured model is unavailable (Google retires model IDs regularly)
+GEMINI_FALLBACK_MODELS = [m.strip() for m in os.getenv(
+    "GEMINI_FALLBACK_MODELS", "gemini-3.6-flash,gemini-flash-latest,gemini-2.5-flash").split(",") if m.strip()]
+PINECONE_INDEX = os.getenv("PINECONE_INDEX", "interview-speaker-embeddings")
+SPEAKER_MATCH_THRESHOLD = float(os.getenv("SPEAKER_MATCH_THRESHOLD", "0.7"))
+TRANSCRIPTION_TIMEOUT_S = int(os.getenv("TRANSCRIPTION_TIMEOUT_S", "900"))
+
+ASSEMBLYAI_BASE = "https://api.assemblyai.com/v2"
+FILLER_PATTERN = re.compile(
+    r"\b(um+|uh+|uhm+|erm*|ah+|hmm+|mhm|you know|i mean|kind of|sort of|basically|actually|like)\b"
+)
+QUESTION_WORDS = re.compile(r"\b(why|how|what|when|where|who|which|tell me|describe|can you|could you)\b")
+
+
+def validate_env_vars() -> Dict[str, bool]:
+    """Report which external services are configured. Only AssemblyAI is mandatory."""
+    status = {
+        "assemblyai": bool(ASSEMBLYAI_API_KEY),
+        "pinecone": bool(PINECONE_API_KEY),  # optional: falls back to the built-in local index
+        "gemini": bool(GEMINI_API_KEY),
+    }
+    for name, ok in status.items():
+        if not ok:
+            level = logging.ERROR if name == "assemblyai" else logging.WARNING
+            logger.log(level, "%s API key not set; %s", name,
+                       "transcription will fail" if name == "assemblyai" else "using the built-in local speaker index" if name == "pinecone" else "this step will be skipped")
+    return status
+
+
+# --------------------------------------------------------------------------------------
+# Lazy service / model initialization (loaded once, on first use)
+# --------------------------------------------------------------------------------------
+_init_lock = threading.Lock()
+_services: Dict[str, object] = {}
+
+
+def _get_speaker_model():
+    with _init_lock:
+        if "speaker_model" not in _services:
+            import torch
+            from nemo.collections.asr.models import EncDecSpeakerLabelModel
+
+            torch.set_num_threads(max(1, os.cpu_count() or 1))
+            logger.info("Loading NVIDIA TitaNet speaker verification model...")
+            model = EncDecSpeakerLabelModel.from_pretrained(
+                "nvidia/speakerverification_en_titanet_large", map_location=torch.device("cpu")
+            )
+            model.eval()
+            _services["speaker_model"] = model
+        return _services["speaker_model"]
+
+
+class LocalSpeakerIndex:
+    """Small built-in vector store used when Pinecone is not configured.
+
+    Stores L2-normalized speaker embeddings in a .npz file and matches by cosine
+    similarity. Mirrors the subset of the Pinecone Index API that the pipeline uses.
+    """
+
+    def __init__(self, path: str):
+        self.path = path
+        self._lock = threading.Lock()
+        self.ids: List[str] = []
+        self.names: List[str] = []
+        self.vectors = np.zeros((0, 192), dtype=np.float32)
+        if os.path.exists(path):
+            try:
+                data = np.load(path, allow_pickle=False)
+                self.ids, self.names = list(data["ids"]), list(data["names"])
+                self.vectors = data["vectors"].astype(np.float32)
+            except Exception as e:
+                logger.warning("Could not load local speaker index (%s); starting empty", e)
+
+    def query(self, vector, top_k=1, include_metadata=True):
+        with self._lock:
+            if not len(self.ids):
+                return {"matches": []}
+            v = np.asarray(vector, dtype=np.float32)
+            v = v / (np.linalg.norm(v) + 1e-9)
+            scores = self.vectors @ v
+            order = np.argsort(-scores)[:top_k]
+            return {"matches": [{"id": self.ids[i], "score": float(scores[i]),
+                                 "metadata": {"speaker_name": self.names[i]}} for i in order]}
+
+    def upsert(self, vectors):
+        with self._lock:
+            for item in vectors:
+                v = np.asarray(item["values"], dtype=np.float32)
+                v = v / (np.linalg.norm(v) + 1e-9)
+                self.ids.append(item["id"])
+                self.names.append(item.get("metadata", {}).get("speaker_name", item["id"]))
+                self.vectors = np.vstack([self.vectors, v[None, :]])
+            tmp = self.path + ".tmp.npz"
+            np.savez(tmp, ids=np.array(self.ids), names=np.array(self.names), vectors=self.vectors)
+            os.replace(tmp, self.path)
+
+
+def _local_index_path() -> str:
+    # /data is the persistent-storage mount on Hugging Face Spaces (if enabled)
+    base = os.getenv("SPEAKER_INDEX_DIR") or ("/data" if os.path.isdir("/data") and os.access("/data", os.W_OK) else MODEL_DIR)
+    os.makedirs(base, exist_ok=True)
+    return os.path.join(base, "speaker_index.npz")
+
+
+def _get_pinecone_index():
+    """Speaker vector index: Pinecone if a key is configured, otherwise the built-in local index."""
+    if not PINECONE_API_KEY:
+        with _init_lock:
+            if "local_index" not in _services:
+                _services["local_index"] = LocalSpeakerIndex(_local_index_path())
+                logger.info("Using built-in local speaker index at %s", _services["local_index"].path)
+            return _services["local_index"]
+    with _init_lock:
+        if "pinecone_index" not in _services:
+            from pinecone import Pinecone, ServerlessSpec
+
+            pc = Pinecone(api_key=PINECONE_API_KEY)
+            existing = [i["name"] for i in pc.list_indexes()]
+            if PINECONE_INDEX not in existing:
+                logger.info("Creating Pinecone index %s", PINECONE_INDEX)
+                pc.create_index(
+                    name=PINECONE_INDEX, dimension=192, metric="cosine",
+                    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
+                )
+                while not pc.describe_index(PINECONE_INDEX).status["ready"]:
+                    time.sleep(1)
+            _services["pinecone_index"] = pc.Index(PINECONE_INDEX)
+        return _services["pinecone_index"]
+
+
+def _get_gemini_client():
+    if not GEMINI_API_KEY:
+        return None
+    with _init_lock:
+        if "gemini" not in _services:
+            from google import genai
+            from google.genai import types
+
+            _services["gemini"] = genai.Client(
+                api_key=GEMINI_API_KEY, http_options=types.HttpOptions(timeout=GEMINI_TIMEOUT_S * 1000))
+        return _services["gemini"]
+
+
+def load_models() -> None:
+    """Warm up everything at startup so the first request is not slow."""
+    validate_env_vars()
+    get_role_classifier()
+    _get_speaker_model()
+    try:
+        _get_pinecone_index()
+    except Exception as e:  # Pinecone is optional
+        logger.warning("Pinecone unavailable: %s", e)
+
+
+# --------------------------------------------------------------------------------------
+# 1. Audio conversion
+# --------------------------------------------------------------------------------------
+def convert_to_wav(input_path: str, output_dir: str = OUTPUT_DIR) -> str:
+    os.makedirs(output_dir, exist_ok=True)
+    output_path = os.path.join(output_dir, f"{uuid.uuid4().hex}.wav")
+    command = ["ffmpeg", "-y", "-loglevel", "error", "-i", input_path, "-vn",
+               "-acodec", "pcm_s16le", "-ar", "16000", "-ac", "1", output_path]
+    result = subprocess.run(command, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise ValueError(f"Could not read the audio file: {result.stderr.strip()[:300]}")
+    logger.info("Converted to WAV (%.2f MB)", os.path.getsize(output_path) / 1024 / 1024)
+    return output_path
+
+
+# --------------------------------------------------------------------------------------
+# 2. Transcription (AssemblyAI, with speaker labels and disfluencies kept)
+# --------------------------------------------------------------------------------------
+def transcribe(audio_path: str, speakers_expected: Optional[int] = 2, diarize: bool = True) -> Dict:
+    if not ASSEMBLYAI_API_KEY:
+        raise RuntimeError("ASSEMBLYAI_API_KEY is not configured")
+    headers = {"authorization": ASSEMBLYAI_API_KEY}
+
+    with open(audio_path, "rb") as f:
+        upload = requests.post(f"{ASSEMBLYAI_BASE}/upload", headers=headers, data=f, timeout=300)
+    upload.raise_for_status()
+    audio_url = upload.json()["upload_url"]
+
+    payload = {
+        "audio_url": audio_url,
+        "speaker_labels": diarize,
+        "disfluencies": True,  # keep "um"/"uh" so filler-word analysis is meaningful
+        "speech_models": ["universal-2"],
+        "language_code": "en",
+    }
+    if diarize and speakers_expected:
+        payload["speakers_expected"] = speakers_expected
+    job = requests.post(f"{ASSEMBLYAI_BASE}/transcript", headers=headers, json=payload, timeout=60)
+    if job.status_code != 200:
+        raise RuntimeError(f"AssemblyAI rejected the request: {job.status_code} {job.text[:300]}")
+    transcript_id = job.json()["id"]
+
+    deadline = time.time() + TRANSCRIPTION_TIMEOUT_S
+    while time.time() < deadline:
+        poll = requests.get(f"{ASSEMBLYAI_BASE}/transcript/{transcript_id}", headers=headers, timeout=60)
+        poll.raise_for_status()
+        result = poll.json()
+        if result["status"] == "completed":
+            return result
+        if result["status"] == "error":
+            raise RuntimeError(f"AssemblyAI error: {result.get('error')}")
+        time.sleep(3)
+    raise TimeoutError("Transcription timed out")
+
+
+# --------------------------------------------------------------------------------------
+# 3. Prosodic features
+# --------------------------------------------------------------------------------------
+EMPTY_PROSODY = {k: 0.0 for k in ("duration", "mean_pitch", "min_pitch", "max_pitch", "pitch_sd",
+                                  "intensityMean", "intensityMin", "intensityMax", "intensitySD")}
+
+
+def extract_prosodic_features(y: np.ndarray, sr: int, start_ms: int, end_ms: int) -> Dict:
+    segment = y[int(start_ms * sr / 1000): int(end_ms * sr / 1000)]
+    if len(segment) < sr // 10:
+        return {**EMPTY_PROSODY, "duration": (end_ms - start_ms) / 1000}
+    try:
+        pitches = librosa.piptrack(y=segment, sr=sr, fmin=60, fmax=400)[0]
+        pitches = pitches[pitches > 0]
+        rms = librosa.feature.rms(y=segment)[0]
+        has_pitch = len(pitches) > 0
+        return {
+            "duration": (end_ms - start_ms) / 1000,
+            "mean_pitch": float(np.mean(pitches)) if has_pitch else 0.0,
+            "min_pitch": float(np.min(pitches)) if has_pitch else 0.0,
+            "max_pitch": float(np.max(pitches)) if has_pitch else 0.0,
+            "pitch_sd": float(np.std(pitches)) if has_pitch else 0.0,
+            "intensityMean": float(np.mean(rms)),
+            "intensityMin": float(np.min(rms)),
+            "intensityMax": float(np.max(rms)),
+            "intensitySD": float(np.std(rms)),
+        }
+    except Exception as e:
+        logger.warning("Prosodic feature extraction failed: %s", e)
+        return {**EMPTY_PROSODY, "duration": (end_ms - start_ms) / 1000}
+
+
+# --------------------------------------------------------------------------------------
+# 4. Speaker identification (TitaNet embeddings + Pinecone)
+# --------------------------------------------------------------------------------------
+def _speaker_embedding(y: np.ndarray, sr: int, utterances: List[Dict], max_seconds: float = 45.0) -> np.ndarray:
+    """One embedding per diarized speaker, from up to `max_seconds` of their speech."""
+    chunks, total = [], 0.0
+    for u in sorted(utterances, key=lambda u: u["end"] - u["start"], reverse=True):
+        seg = y[int(u["start"] * sr / 1000): int(u["end"] * sr / 1000)]
+        chunks.append(seg)
+        total += len(seg) / sr
+        if total >= max_seconds:
+            break
+    audio = np.concatenate(chunks) if chunks else np.zeros(sr, dtype=np.float32)
+    tmp = os.path.join(OUTPUT_DIR, f"spk_{uuid.uuid4().hex}.wav")
+    sf.write(tmp, audio, sr)
+    try:
+        import torch
+
+        with torch.no_grad():
+            emb = _get_speaker_model().get_embedding(tmp).cpu().numpy().flatten()
+        return emb / (np.linalg.norm(emb) + 1e-9)
+    finally:
+        os.remove(tmp)
+
+
+def identify_speakers(transcript: Dict, y: np.ndarray, sr: int, enroll: bool = True) -> Dict[str, Dict]:
+    """Map each diarization label (A, B, ...) to a persistent speaker identity."""
+    by_label: Dict[str, List[Dict]] = {}
+    for u in transcript["utterances"]:
+        by_label.setdefault(u["speaker"], []).append(u)
+
+    index = None
+    try:
+        index = _get_pinecone_index()
+    except Exception as e:
+        logger.warning("Pinecone unavailable, skipping speaker matching: %s", e)
+
+    speakers = {}
+    for label, utts in by_label.items():
+        info = {"label": label, "speaker_id": f"session_{label}", "speaker_name": f"Speaker {label}",
+                "matched_existing": False, "match_score": None}
+        try:
+            emb = _speaker_embedding(y, sr, utts)
+            if index is not None:
+                res = index.query(vector=emb.tolist(), top_k=1, include_metadata=True)
+                matches = [m if isinstance(m, dict) else m.to_dict() for m in (res["matches"] or [])]
+                if matches and matches[0]["score"] >= SPEAKER_MATCH_THRESHOLD:
+                    info.update(speaker_id=matches[0]["id"],
+                                speaker_name=matches[0]["metadata"].get("speaker_name", matches[0]["id"]),
+                                matched_existing=True, match_score=round(float(matches[0]["score"]), 3))
+                elif enroll:
+                    new_id = f"spk_{uuid.uuid4().hex[:8]}"
+                    index.upsert(vectors=[{"id": new_id, "values": emb.tolist(),
+                                           "metadata": {"speaker_name": f"Speaker {new_id[-4:]}",
+                                                        "enrolled_at": time.strftime("%Y-%m-%d")}}])
+                    info.update(speaker_id=new_id, speaker_name=f"Speaker {new_id[-4:]}")
+        except Exception as e:
+            logger.warning("Speaker embedding failed for %s: %s", label, e)
+        speakers[label] = info
+    return speakers
+
+
+# --------------------------------------------------------------------------------------
+# 5. Role classification (Random Forest trained on labeled MIT interview transcripts)
+# --------------------------------------------------------------------------------------
+def _handcrafted_features(texts: List[str]) -> np.ndarray:
+    rows = []
+    for t in texts:
+        low = t.lower()
+        words = low.split()
+        n = max(len(words), 1)
+        rows.append([
+            int(t.strip().endswith("?")),
+            t.count("?"),
+            len(QUESTION_WORDS.findall(low)),
+            np.log1p(len(words)),
+            sum(1 for w in words if w in ("i", "i'm", "my", "me", "i've")) / n,
+            sum(1 for w in words if w in ("you", "your", "you're")) / n,
+            len(FILLER_PATTERN.findall(low)) / n,
+        ])
+    return np.array(rows, dtype=float)
+
+
+def _load_training_data(path: str):
+    texts, labels, groups = [], [], []
+    with open(path, encoding="utf-8", errors="replace") as f:
+        for row in csv.reader(f):
+            if len(row) < 2:
+                continue
+            for turn in row[1].split("|"):
+                if ":" not in turn:
+                    continue
+                who, text = turn.split(":", 1)
+                who = who.strip().lower()
+                text = re.sub(r"\[.*?\]", " ", text).strip()
+                if not text:
+                    continue
+                if who.startswith("interviewer") or who.startswith("intrviewer"):
+                    labels.append("Interviewer")
+                elif who.startswith("interview") or who.startswith("inerviewee"):
+                    labels.append("Interviewee")
+                else:
+                    continue
+                texts.append(text)
+                groups.append(row[0])
+    return texts, labels, groups
+
+
+def _build_role_pipeline() -> Pipeline:
+    return Pipeline([
+        ("features", FeatureUnion([
+            ("tfidf", TfidfVectorizer(max_features=3000, ngram_range=(1, 2), sublinear_tf=True)),
+            ("handcrafted", FunctionTransformer(_handcrafted_features)),
+        ])),
+        ("clf", RandomForestClassifier(n_estimators=300, min_samples_leaf=2, class_weight="balanced",
+                                       random_state=42, n_jobs=-1)),
+    ])
+
+
+def train_role_classifier(csv_path: str = TRAINING_CSV) -> Pipeline:
+    texts, labels, groups = _load_training_data(csv_path)
+    # Hold out whole interviews to get an honest accuracy estimate
+    split = GroupShuffleSplit(n_splits=1, test_size=0.2, random_state=42)
+    train_idx, test_idx = next(split.split(texts, labels, groups))
+    model = _build_role_pipeline()
+    model.fit([texts[i] for i in train_idx], [labels[i] for i in train_idx])
+    acc = model.score([texts[i] for i in test_idx], [labels[i] for i in test_idx])
+    logger.info("Role classifier: %d utterances, held-out utterance accuracy %.3f", len(texts), acc)
+
+    model = _build_role_pipeline().fit(texts, labels)
+    model.heldout_accuracy_ = float(acc)
+    joblib.dump(model, os.path.join(MODEL_DIR, "role_classifier.joblib"))
+    return model
+
+
+BUNDLED_ROLE_MODEL = os.path.join(os.path.dirname(os.path.abspath(__file__)), "assets", "models", "role_classifier.joblib")
+
+
+def get_role_classifier() -> Pipeline:
+    """Load the pre-trained role classifier.
+
+    The model ships with the app (assets/models). The training transcripts come from the
+    MIT Interview Dataset, whose license does not allow redistribution, so they are not
+    included; retraining only happens if EVALBOT_TRAINING_CSV points to a local copy.
+    """
+    with _init_lock:
+        if "role_clf" not in _services:
+            model = None
+            for path in (os.path.join(MODEL_DIR, "role_classifier.joblib"), BUNDLED_ROLE_MODEL):
+                if os.path.exists(path):
+                    try:
+                        model = joblib.load(path)
+                        break
+                    except Exception as e:
+                        logger.warning("Could not load role classifier from %s (%s)", path, e)
+            _services["role_clf"] = model
+    if _services["role_clf"] is None:
+        if not os.path.exists(TRAINING_CSV):
+            raise RuntimeError("Role classifier model not found and no training data available")
+        _services["role_clf"] = train_role_classifier()
+    return _services["role_clf"]
+
+
+def classify_roles(utterances: List[Dict]) -> Dict[str, str]:
+    """Assign one role per speaker by aggregating utterance-level probabilities."""
+    model = get_role_classifier()
+    texts = [u["text"] for u in utterances]
+    probs = model.predict_proba(texts)
+    interviewer_col = list(model.classes_).index("Interviewer")
+
+    score: Dict[str, float] = {}
+    weight: Dict[str, float] = {}
+    for u, p in zip(utterances, probs):
+        w = np.log1p(len(u["text"].split()))
+        score[u["speaker"]] = score.get(u["speaker"], 0.0) + w * p[interviewer_col]
+        weight[u["speaker"]] = weight.get(u["speaker"], 0.0) + w
+    interviewer_prob = {s: score[s] / weight[s] for s in score if weight[s] > 0}
+
+    if len(interviewer_prob) == 1:
+        only = next(iter(interviewer_prob))
+        return {only: "Interviewer" if interviewer_prob[only] > 0.5 else "Interviewee"}
+    interviewer = max(interviewer_prob, key=interviewer_prob.get)
+    return {s: ("Interviewer" if s == interviewer else "Interviewee") for s in interviewer_prob}
+
+
+# --------------------------------------------------------------------------------------
+# 6. Interviewee voice analysis
+# --------------------------------------------------------------------------------------
+def analyze_interviewee_voice(y: np.ndarray, sr: int, utterances: List[Dict]) -> Dict:
+    interviewee = [u for u in utterances if u["role"] == "Interviewee"]
+    if not interviewee:
+        return {"error": "No interviewee speech detected"}
+
+    segments = [y[int(u["start"] * sr / 1000): int(u["end"] * sr / 1000)] for u in interviewee]
+    segments = [s for s in segments if len(s) > sr // 10]
+
+    total_duration = sum(u["prosodic_features"]["duration"] for u in interviewee)
+    words = " ".join(u["text"].lower() for u in interviewee)
+    word_list = re.findall(r"[a-z']+", words)
+    total_words = len(word_list)
+    speaking_rate = total_words / total_duration if total_duration > 0 else 0.0
+
+    filler_hits = FILLER_PATTERN.findall(words)
+    filler_ratio = len(filler_hits) / total_words if total_words else 0.0
+    filler_breakdown: Dict[str, int] = {}
+    for f in filler_hits:
+        filler_breakdown[f] = filler_breakdown.get(f, 0) + 1
+
+    bigrams = list(zip(word_list, word_list[1:]))
+    immediate_repeats = sum(1 for a, b in zip(word_list, word_list[1:]) if a == b)
+    bigram_counts: Dict[tuple, int] = {}
+    for bg in bigrams:
+        bigram_counts[bg] = bigram_counts.get(bg, 0) + 1
+    repeated_bigrams = sum(c - 1 for c in bigram_counts.values() if c > 1)
+    repetition_score = (immediate_repeats + 0.25 * repeated_bigrams) / total_words if total_words else 0.0
+
+    pitches: List[float] = []
+    for seg in segments:
+        f0, voiced, _ = librosa.pyin(seg, fmin=70, fmax=350, sr=sr, frame_length=1024)
+        pitches.extend(f0[voiced & ~np.isnan(f0)].tolist())
+    pitches_arr = np.array(pitches)
+    pitch_mean = float(pitches_arr.mean()) if len(pitches_arr) else 0.0
+    pitch_std = float(pitches_arr.std()) if len(pitches_arr) else 0.0
+    jitter = float(np.mean(np.abs(np.diff(pitches_arr))) / pitch_mean) if len(pitches_arr) > 1 and pitch_mean else 0.0
+
+    intensities = np.concatenate([librosa.feature.rms(y=s)[0] for s in segments]) if segments else np.array([])
+    intensity_mean = float(intensities.mean()) if len(intensities) else 0.0
+    intensity_std = float(intensities.std()) if len(intensities) else 0.0
+    shimmer = float(np.mean(np.abs(np.diff(intensities))) / intensity_mean) if len(intensities) > 1 and intensity_mean else 0.0
+
+    # Heuristic composite scores, clamped to [0, 1]
+    pitch_cv = pitch_std / pitch_mean if pitch_mean else 0.0
+    anxiety = float(np.clip(0.6 * pitch_cv + 0.4 * (jitter + shimmer) / 2, 0, 1))
+    rate_penalty = min(abs(speaking_rate - 2.5) / 2.5, 1.0)
+    intensity_cv = intensity_std / intensity_mean if intensity_mean else 1.0
+    confidence = float(np.clip(1 - (0.35 * min(intensity_cv, 1) + 0.35 * min(filler_ratio * 8, 1)
+                                     + 0.15 * rate_penalty + 0.15 * anxiety), 0, 1))
+    hesitation = float(np.clip(filler_ratio * 5 + repetition_score * 5, 0, 1))
+
+    def level(v, hi, mid, labels=("high", "moderate", "low")):
+        return labels[0] if v > hi else labels[1] if v > mid else labels[2]
+
+    fluency = ("fluent" if filler_ratio < 0.03 and repetition_score < 0.02 else
+               "moderate" if filler_ratio < 0.07 and repetition_score < 0.05 else "disfluent")
+
+    return {
+        "speaking_rate": round(speaking_rate, 2),
+        "speaking_time_seconds": round(total_duration, 1),
+        "word_count": total_words,
+        "filler_ratio": round(filler_ratio, 4),
+        "filler_words": dict(sorted(filler_breakdown.items(), key=lambda kv: -kv[1])),
+        "repetition_score": round(repetition_score, 4),
+        "pitch_analysis": {"mean_hz": round(pitch_mean, 1), "std_dev_hz": round(pitch_std, 1),
+                           "jitter": round(jitter, 4)},
+        "intensity_analysis": {"mean_rms": round(intensity_mean, 4), "std_dev_rms": round(intensity_std, 4),
+                               "shimmer": round(shimmer, 4)},
+        "composite_scores": {"anxiety": round(anxiety, 3), "confidence": round(confidence, 3),
+                             "hesitation": round(hesitation, 3)},
+        "interpretation": {"anxiety_level": level(anxiety, 0.35, 0.18),
+                           "confidence_level": level(confidence, 0.7, 0.5),
+                           "fluency_level": fluency},
+    }
+
+
+# --------------------------------------------------------------------------------------
+# Question / answer pairing
+# --------------------------------------------------------------------------------------
+def build_qa_pairs(utterances: List[Dict], max_pairs: int = 25) -> List[Dict]:
+    """Merge consecutive turns by role, then pair each interviewer block with the answer after it."""
+    blocks: List[Dict] = []
+    for u in utterances:
+        if blocks and blocks[-1]["role"] == u["role"]:
+            blocks[-1]["text"] += " " + u["text"]
+            blocks[-1]["end"] = u["end"]
+        else:
+            blocks.append({"role": u["role"], "text": u["text"], "start": u["start"], "end": u["end"]})
+    pairs = []
+    for q, a in zip(blocks, blocks[1:]):
+        if q["role"] == "Interviewer" and a["role"] == "Interviewee" and len(a["text"].split()) >= 4:
+            pairs.append({"index": len(pairs) + 1, "question": q["text"], "answer": a["text"],
+                          "question_start": q["start"], "answer_start": a["start"], "answer_end": a["end"],
+                          "answer_seconds": round((a["end"] - a["start"]) / 1000, 1)})
+            if len(pairs) >= max_pairs:
+                break
+    return pairs
+
+
+# --------------------------------------------------------------------------------------
+# 7. Evaluation with Gemini (structured JSON output)
+# --------------------------------------------------------------------------------------
+EVALUATION_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "content_score": {"type": "integer", "description": "0-100 quality of the answers' content"},
+        "executive_summary": {"type": "array", "items": {"type": "string"}},
+        "communication": {"type": "array", "items": {"type": "string"}},
+        "communication_tip": {"type": "string"},
+        "strengths": {"type": "array", "items": {"type": "object", "properties": {
+            "competency": {"type": "string"}, "explanation": {"type": "string"},
+            "evidence": {"type": "string"}}, "required": ["competency", "explanation", "evidence"]}},
+        "weaknesses": {"type": "array", "items": {"type": "object", "properties": {
+            "area": {"type": "string"}, "feedback": {"type": "string"}},
+            "required": ["area", "feedback"]}},
+        "questions": {"type": "array", "items": {"type": "object", "properties": {
+            "index": {"type": "integer"},
+            "score": {"type": "integer", "description": "0-10"},
+            "what_went_well": {"type": "string"},
+            "what_to_improve": {"type": "string"},
+            "improved_answer": {"type": "string"}},
+            "required": ["index", "score", "what_went_well", "what_to_improve", "improved_answer"]}},
+        "role_fit": {"type": "array", "items": {"type": "string"}},
+        "recommendations": {"type": "array", "items": {"type": "object", "properties": {
+            "category": {"type": "string", "enum": ["Communication Skills", "Content Delivery",
+                                                    "Professional Presentation"]},
+            "recommendation": {"type": "string"}, "how_to": {"type": "string"}},
+            "required": ["category", "recommendation", "how_to"]}},
+        "next_steps": {"type": "array", "items": {"type": "string"}},
+    },
+    "required": ["content_score", "executive_summary", "communication", "communication_tip", "strengths",
+                 "weaknesses", "questions", "role_fit", "recommendations", "next_steps"],
+}
+
+
+def _language_rule(lang: str) -> str:
+    if lang == "ar":
+        return ("- Write ALL free-text values in clear Modern Standard Arabic. Keep technical terms "
+                "(e.g. API, Spark, SQL) and direct quotes from the transcript in English.\n"
+                "- improved_answer must stay in ENGLISH, because the interview itself is in English.\n")
+    return "- Write all text in English.\n"
+
+
+def _gemini_json(prompt: str, schema: Dict, temperature: float = 0.4) -> Optional[Dict]:
+    client = _get_gemini_client()
+    if client is None:
+        return None
+    from google.genai import types
+
+    global GEMINI_MODEL
+    models = [GEMINI_MODEL] + [m for m in GEMINI_FALLBACK_MODELS if m != GEMINI_MODEL]
+    config = types.GenerateContentConfig(response_mime_type="application/json",
+                                         response_schema=schema, temperature=temperature)
+    for model in models:
+        for attempt in range(3):
+            try:
+                t0 = time.time()
+                response = client.models.generate_content(model=model, contents=prompt, config=config)
+                logger.info("Gemini %s answered in %.1fs", model, time.time() - t0)
+                if model != GEMINI_MODEL:
+                    logger.info("Switching Gemini model to %s", model)
+                    GEMINI_MODEL = model
+                return json.loads(response.text)
+            except Exception as e:
+                msg = str(e).lower()
+                unavailable = any(k in msg for k in ("not found", "404", "is not supported", "no longer available",
+                                                     "deprecated", "permission_denied", "not available"))
+                overloaded = any(k in msg for k in ("503", "unavailable", "high demand", "overloaded", "429",
+                                                    "resource_exhausted", "timed out", "timeout", "deadline"))
+                logger.warning("Gemini (%s) attempt %d failed: %s", model, attempt + 1, str(e)[:300])
+                if unavailable or (overloaded and attempt >= 1):
+                    break  # try the next model
+                time.sleep(1.5 * (attempt + 1))
+    return None
+
+
+def _format_transcript(utterances: List[Dict], limit_chars: int = 50000) -> str:
+    return "\n".join(f"{u['role']}: {u['text']}" for u in utterances)[:limit_chars]
+
+
+def generate_evaluation(analysis: Dict, lang: str = "en") -> Optional[Dict]:
+    voice = analysis["voice_analysis"]
+    metrics = ({k: voice.get(k) for k in ("speaking_rate", "filler_ratio", "repetition_score",
+                                          "composite_scores", "interpretation")}
+               if "error" not in voice else voice)
+    qa_text = "\n\n".join(f"[{p['index']}] Q: {p['question']}\n    A: {p['answer']}" for p in analysis["qa_pairs"])
+    prompt = f"""You are EvalBot, a senior HR analyst and interview coach. Evaluate the INTERVIEWEE.
+
+Rules:
+- Base every point on what the interviewee actually said (quote or paraphrase as evidence) or on the metrics.
+- Be specific, professional and constructive. No generic filler. Do not invent facts about the candidate.
+- 4-8 strengths, 3-8 weaknesses, exactly 5 recommendations, 5 next steps, 3 bullets each for
+  executive summary, communication and role fit.
+- content_score: 0-100 for the quality, relevance and depth of the answers (not the voice).
+- questions: one entry per numbered question-answer pair below, using the same index.
+  score is 0-10 for that answer. improved_answer is a stronger version of the candidate's answer
+  (3-5 sentences, first person, STAR structure where it fits) that reuses only facts the candidate
+  mentioned; where a concrete detail would help, write a placeholder like [number] or [tool].
+{_language_rule(lang)}
+Vocal metrics (computed from audio):
+{json.dumps(metrics, indent=1)}
+Interview duration: {analysis['interview']['duration_seconds']:.0f} s, speaker turns: {analysis['interview']['speaker_turns']}
+
+Question-answer pairs:
+{qa_text or '(none detected)'}
+
+Full transcript:
+{_format_transcript(analysis['transcript'])}
+"""
+    return _gemini_json(prompt, EVALUATION_SCHEMA)
+
+
+def fallback_evaluation(analysis: Dict, lang: str = "en") -> Dict:
+    """Metric-only evaluation used when Gemini is not configured or unavailable."""
+    v = analysis["voice_analysis"]
+    empty = {"content_score": None, "communication": [], "communication_tip": "", "strengths": [],
+             "weaknesses": [], "questions": [], "role_fit": [], "recommendations": [], "next_steps": [],
+             "ai_generated": False}
+    if "error" in v:
+        return {**empty, "executive_summary": [v["error"]]}
+    i = v["interpretation"]
+    if lang == "ar":
+        comm = [
+            f"معدل الكلام {v['speaking_rate']} كلمة في الثانية (المعدل الطبيعي للكلام الواضح من 2 إلى 3).",
+            f"كلمات الحشو تمثل {v['filler_ratio'] * 100:.1f}% من كلام المرشّح، ومستوى الطلاقة: {L('ar', i['fluency_level'])}.",
+            f"الثقة الصوتية: {L('ar', i['confidence_level'])}، والقلق: {L('ar', i['anxiety_level'])}، بناءً على ثبات طبقة الصوت وشدته.",
+        ]
+        note = "لم يكن تقييم المحتوى بالذكاء الاصطناعي متاحاً في هذه المرة، فالتقرير مبني على مقاييس الصوت فقط."
+        tip = "توقّف لحظة بدل استخدام كلمات الحشو، ورتّب إجاباتك: الموقف، ثم ما فعلته، ثم النتيجة."
+    else:
+        comm = [
+            f"Speaking rate of {v['speaking_rate']} words/sec "
+            f"({'within' if 2.0 <= v['speaking_rate'] <= 3.0 else 'outside'} the 2-3 words/sec range typical of clear speech).",
+            f"Filler words make up {v['filler_ratio'] * 100:.1f}% of the interviewee's words; fluency is {i['fluency_level']}.",
+            f"Vocal confidence is {i['confidence_level']} and anxiety is {i['anxiety_level']}, based on pitch and loudness stability.",
+        ]
+        note = "Automated content evaluation was unavailable for this run; this report is based on vocal metrics only."
+        tip = "Pause briefly instead of using filler words, and keep answers structured (situation, action, result)."
+    return {**empty, "executive_summary": [note, comm[0]], "communication": comm, "communication_tip": tip}
+
+
+# --------------------------------------------------------------------------------------
+# Suitability score
+# --------------------------------------------------------------------------------------
+def calculate_acceptance_probability(voice: Dict, content_score: Optional[int]) -> float:
+    """Heuristic 0-100 suitability score: 60% answer content (if available), 40% delivery."""
+    if "error" in voice:
+        return float(content_score) if content_score is not None else 0.0
+    cs = voice["composite_scores"]
+    fluency_val = {"fluent": 1.0, "moderate": 0.6, "disfluent": 0.25}[voice["interpretation"]["fluency_level"]]
+    rate_score = max(0.0, 1 - abs(voice["speaking_rate"] - 2.5) / 2.5)
+    delivery = (0.35 * cs["confidence"] + 0.25 * (1 - cs["anxiety"]) + 0.25 * fluency_val + 0.15 * rate_score)
+    if content_score is None:
+        return round(delivery * 100, 1)
+    return round(0.6 * content_score + 0.4 * delivery * 100, 1)
+
+
+def verdict_for(score: Optional[float], lang: str = "en", provisional: bool = False) -> str:
+    if provisional:
+        return L(lang, "verdict_provisional")
+    key = ("verdict_top" if score >= 80 else "verdict_strong" if score >= 65
+           else "verdict_moderate" if score >= 50 else "verdict_low")
+    return L(lang, key)
+
+
+# --------------------------------------------------------------------------------------
+# Labels (English / Arabic)
+# --------------------------------------------------------------------------------------
+LABELS = {
+    "en": {
+        "report_title": "Candidate Interview Analysis", "header": "EvalBot  |  Interview Analysis Report",
+        "footer": "Confidential - generated automatically by EvalBot", "page": "Page",
+        "candidate_id": "Candidate ID", "generated": "Generated",
+        "suitability": "Suitability score", "score_basis": "Content {content} (60%) + vocal delivery (40%)",
+        "interview": "Interview", "duration": "Duration", "minutes": "minutes", "speaker_turns": "Speaker turns",
+        "speakers": "Speakers", "interviewee_time": "Interviewee speaking time", "words": "words",
+        "questions_answered": "Questions answered",
+        "exec_summary": "Executive Summary", "comm_title": "Communication & Vocal Dynamics",
+        "metric": "Metric", "value": "Value", "meaning": "What it means",
+        "speaking_rate": "Speaking rate", "wps": "words/sec", "fillers": "Filler words", "of_words": "of words",
+        "most_frequent": "Most frequent", "none": "none", "repetition": "Repetition", "fluency": "Fluency",
+        "confidence": "Confidence", "anxiety": "Anxiety", "hesitation": "Hesitation", "pitch": "Pitch",
+        "m_rate": "2.0-3.0 words/sec is typical of clear, paced speech.",
+        "m_rep": "Repeated words and phrases; lower is better.", "m_flu": "Combines filler words and repetition.",
+        "m_conf": "Steady loudness, few fillers, comfortable pace.",
+        "m_anx": "Pitch variability and voice instability (jitter / shimmer).",
+        "m_pitch": "Average voice pitch and its variation.",
+        "observations": "Observations", "tip": "Tip for workplace communication",
+        "qa_title": "Question-by-Question Feedback", "question": "Question", "answer": "Answer (excerpt)",
+        "went_well": "What went well", "to_improve": "What to improve", "better_answer": "A stronger answer",
+        "competency_title": "Competency Evaluation", "strengths": "Strengths", "competency": "Competency",
+        "assessment": "Assessment and evidence", "evidence": "Evidence", "dev_areas": "Development areas",
+        "area": "Area", "feedback": "Actionable feedback", "role_fit": "Role Fit & Potential",
+        "recs": "Recommendations for the Candidate", "rec_area": "Area", "recommendation": "Recommendation",
+        "how_to": "How to practice", "next_steps": "Next Steps for Hiring Managers",
+        "appendix": "Appendix: Annotated Transcript",
+        "appendix_note": "Speaker roles were assigned automatically by the role classifier.",
+        "time": "Time", "role": "Role", "text": "Text", "Interviewer": "Interviewer", "Interviewee": "Interviewee",
+        "ai_unavailable": "Note: AI content evaluation was unavailable for this run, so sections that depend on it were omitted.",
+        "chart_vocal": "Vocal dynamics (0 = low, 1 = high)", "chart_talk": "Talk time",
+        "chart_q": "Score per question (0-10)",
+        "high": "High", "moderate": "Moderate", "low": "Low", "fluent": "Fluent", "disfluent": "Disfluent",
+        "Communication Skills": "Communication Skills", "Content Delivery": "Content Delivery",
+        "Professional Presentation": "Professional Presentation",
+        "verdict_top": "Outstanding candidate, recommended for advancement.",
+        "verdict_strong": "Strong candidate, suitable for further evaluation.",
+        "verdict_moderate": "Moderate potential, needs additional assessment.",
+        "verdict_low": "Limited fit at this stage; significant improvement needed.",
+        "verdict_provisional": "Provisional: based on vocal delivery only (answer content was not evaluated).",
+    },
+    "ar": {
+        "report_title": "تحليل مقابلة المرشّح", "header": "EvalBot  |  تقرير تحليل المقابلة",
+        "footer": "سري - تم إنشاؤه تلقائياً بواسطة EvalBot", "page": "صفحة",
+        "candidate_id": "رقم المرشّح", "generated": "تاريخ الإنشاء",
+        "suitability": "درجة الملاءمة", "score_basis": "المحتوى {content} (60%) + الأداء الصوتي (40%)",
+        "interview": "المقابلة", "duration": "المدة", "minutes": "دقيقة", "speaker_turns": "عدد المداخلات",
+        "speakers": "المتحدثون", "interviewee_time": "مدة كلام المرشّح", "words": "كلمة",
+        "questions_answered": "عدد الأسئلة المُجاب عليها",
+        "exec_summary": "الملخص التنفيذي", "comm_title": "التواصل والأداء الصوتي",
+        "metric": "المقياس", "value": "القيمة", "meaning": "المعنى",
+        "speaking_rate": "معدل الكلام", "wps": "كلمة/ثانية", "fillers": "كلمات الحشو", "of_words": "من الكلمات",
+        "most_frequent": "الأكثر تكراراً", "none": "لا يوجد", "repetition": "التكرار", "fluency": "الطلاقة",
+        "confidence": "الثقة", "anxiety": "القلق", "hesitation": "التردد", "pitch": "طبقة الصوت",
+        "m_rate": "من 2 إلى 3 كلمات في الثانية هو المعدل المعتاد للكلام الواضح.",
+        "m_rep": "تكرار الكلمات والعبارات، وكلما قلّ كان أفضل.", "m_flu": "يجمع بين كلمات الحشو والتكرار.",
+        "m_conf": "ثبات شدة الصوت، وقلة كلمات الحشو، وسرعة مريحة.",
+        "m_anx": "تذبذب طبقة الصوت وعدم ثباته.", "m_pitch": "متوسط طبقة الصوت ومدى تغيّرها.",
+        "observations": "ملاحظات", "tip": "نصيحة للتواصل في بيئة العمل",
+        "qa_title": "تقييم كل سؤال على حدة", "question": "السؤال", "answer": "الإجابة (مقتطف)",
+        "went_well": "ما كان جيداً", "to_improve": "ما يحتاج إلى تحسين", "better_answer": "إجابة أقوى",
+        "competency_title": "تقييم الكفاءات", "strengths": "نقاط القوة", "competency": "الكفاءة",
+        "assessment": "التقييم والدليل", "evidence": "الدليل", "dev_areas": "مجالات التطوير",
+        "area": "المجال", "feedback": "ملاحظات قابلة للتطبيق", "role_fit": "الملاءمة للدور والإمكانات",
+        "recs": "توصيات للمرشّح", "rec_area": "المجال", "recommendation": "التوصية",
+        "how_to": "طريقة التدريب", "next_steps": "الخطوات التالية لمسؤولي التوظيف",
+        "appendix": "ملحق: نص المقابلة",
+        "appendix_note": "تم تحديد دور كل متحدث تلقائياً بواسطة نموذج تصنيف الأدوار.",
+        "time": "الوقت", "role": "الدور", "text": "النص", "Interviewer": "المحاوِر", "Interviewee": "المرشّح",
+        "ai_unavailable": "ملاحظة: لم يكن تقييم المحتوى بالذكاء الاصطناعي متاحاً، فتم حذف الأقسام المعتمدة عليه.",
+        "chart_vocal": "الأداء الصوتي (0 = منخفض، 1 = مرتفع)", "chart_talk": "توزيع وقت الكلام",
+        "chart_q": "درجة كل سؤال (من 10)",
+        "high": "مرتفع", "moderate": "متوسط", "low": "منخفض", "fluent": "طليق", "disfluent": "متقطع",
+        "Communication Skills": "مهارات التواصل", "Content Delivery": "تقديم المحتوى",
+        "Professional Presentation": "الحضور المهني",
+        "verdict_top": "مرشّح متميز، يُنصح بانتقاله للمرحلة التالية.",
+        "verdict_strong": "مرشّح قوي، مناسب لمزيد من التقييم.",
+        "verdict_moderate": "إمكانات متوسطة، يحتاج إلى تقييم إضافي.",
+        "verdict_low": "ملاءمة محدودة حالياً، ويحتاج إلى تحسين كبير.",
+        "verdict_provisional": "مبدئي: مبني على الأداء الصوتي فقط (لم يتم تقييم محتوى الإجابات).",
+    },
+}
+
+
+def L(lang: str, key: str) -> str:
+    return LABELS.get(lang, LABELS["en"]).get(key, LABELS["en"].get(key, key))
+
+
+# --------------------------------------------------------------------------------------
+# 8. Charts + PDF report (English left-to-right, Arabic right-to-left)
+# --------------------------------------------------------------------------------------
+from reportlab.lib.enums import TA_CENTER, TA_LEFT  # noqa: E402
+from reportlab.pdfbase import pdfmetrics  # noqa: E402
+from reportlab.pdfbase.ttfonts import TTFont  # noqa: E402
+from reportlab.platypus import Flowable  # noqa: E402
+
+FONT_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "assets", "fonts")
+BRAND = colors.HexColor("#0B3D91")
+ACCENT = colors.HexColor("#1F6FEB")
+MUTED = colors.HexColor("#5B6573")
+INK = colors.HexColor("#222222")
+GRID = colors.HexColor("#DDE4EE")
+SOFT = colors.HexColor("#F4F7FB")
+GOOD_BG = colors.HexColor("#EEF8EF")
+BAD_BG = colors.HexColor("#FDF1F1")
+ARABIC_RE = re.compile(r"[؀-ۿ]")
+_fonts_registered = False
+
+
+def _register_fonts() -> bool:
+    global _fonts_registered
+    if _fonts_registered:
+        return True
+    try:
+        pdfmetrics.registerFont(TTFont("Amiri", os.path.join(FONT_DIR, "Amiri-Regular.ttf")))
+        pdfmetrics.registerFont(TTFont("Amiri-Bold", os.path.join(FONT_DIR, "Amiri-Bold.ttf")))
+        _fonts_registered = True
+    except Exception as e:
+        logger.warning("Arabic font not available: %s", e)
+    return _fonts_registered
+
+
+def _get_display(text: str) -> str:
+    # bidi.algorithm implements the full Unicode bidi algorithm, including bracket mirroring
+    try:
+        from bidi.algorithm import get_display
+    except ImportError:
+        from bidi import get_display
+    return get_display(text)
+
+
+def _shape(text: str) -> str:
+    """Arabic letter shaping + bidi reordering for one visual line."""
+    import arabic_reshaper
+    return _get_display(arabic_reshaper.reshape(text))
+
+
+class RTLParagraph(Flowable):
+    """Right-to-left paragraph: wraps in logical order, then reorders each line for display."""
+
+    def __init__(self, text, font="Amiri", size=10, leading=None, color=INK, align="right",
+                 space_before=0, space_after=4, lines=None):
+        super().__init__()
+        self.text = str(text)
+        self.font, self.size = font, size
+        self.leading = leading or size * 1.55
+        self.color, self.align = color, align
+        self.space_before, self.space_after = space_before, space_after
+        self._lines = lines
+        self._width = 0
+
+    def _break(self, width):
+        import arabic_reshaper
+        words = arabic_reshaper.reshape(self.text.replace("\n", " ")).split()
+        lines, cur = [], ""
+        for w in words:
+            trial = f"{cur} {w}".strip()
+            if pdfmetrics.stringWidth(trial, self.font, self.size) <= width or not cur:
+                cur = trial
+            else:
+                lines.append(cur)
+                cur = w
+        if cur:
+            lines.append(cur)
+        return lines or [""]
+
+    def wrap(self, aw, ah):
+        self._width = aw
+        if self._lines is None:
+            self._lines = self._break(aw)
+        return aw, self.space_before + len(self._lines) * self.leading + self.space_after
+
+    def split(self, aw, ah):
+        lines = self._lines if self._lines is not None else self._break(aw)
+        fit = int((ah - self.space_before) // self.leading)
+        if fit <= 0:
+            return []
+        if fit >= len(lines):
+            return [self]
+        kw = dict(font=self.font, size=self.size, leading=self.leading, color=self.color, align=self.align)
+        return [RTLParagraph(self.text, space_before=self.space_before, space_after=0, lines=lines[:fit], **kw),
+                RTLParagraph(self.text, space_before=0, space_after=self.space_after, lines=lines[fit:], **kw)]
+
+    def draw(self):
+        c = self.canv
+        c.setFont(self.font, self.size)
+        c.setFillColor(self.color)
+        total = self.space_before + len(self._lines) * self.leading + self.space_after
+        for i, line in enumerate(self._lines):
+            y = total - self.space_before - (i + 1) * self.leading + (self.leading - self.size) * 0.55
+            visual = _get_display(line)
+            if self.align == "center":
+                c.drawCentredString(self._width / 2, y, visual)
+            else:
+                c.drawRightString(self._width, y, visual)
+
+
+class ReportBuilder:
+    """Creates paragraphs/tables in the right direction and font for the report language."""
+
+    STYLES = {  # size, leading, color, bold, space_before, space_after
+        "title": (24, 30, BRAND, True, 0, 4), "subtitle": (11, 15, MUTED, False, 0, 4),
+        "h1": (15, 20, BRAND, True, 6, 10), "h2": (11.5, 15, ACCENT, True, 10, 6),
+        "body": (9.5, 13.5, INK, False, 0, 4), "small": (8.5, 11.5, MUTED, False, 0, 4),
+        "bullet": (9.5, 13.5, INK, False, 0, 3), "th": (9.5, 12, colors.white, True, 0, 0),
+        "td": (9.5, 13, INK, False, 0, 0), "tdb": (9.5, 13, INK, True, 0, 0),
+    }
+
+    def __init__(self, lang: str):
+        self.lang = lang
+        self.rtl = lang == "ar" and _register_fonts()
+        if lang == "ar" and not self.rtl:
+            self.lang = "en"
+        self._pstyles = {}
+        for name, (size, leading, color, bold, sb, sa) in self.STYLES.items():
+            self._pstyles[name] = ParagraphStyle(
+                name, fontName="Helvetica-Bold" if bold else "Helvetica", fontSize=size, leading=leading,
+                textColor=color, spaceBefore=sb, spaceAfter=sa,
+                alignment=TA_CENTER if name in ("title", "subtitle") else TA_LEFT,
+                leftIndent=14 if name == "bullet" else 0, bulletIndent=4 if name == "bullet" else 0)
+
+    def t(self, key):
+        return L(self.lang, key)
+
+    def p(self, text, kind="body", ltr=False):
+        """Paragraph; English content inside an Arabic report (e.g. the transcript) can be forced LTR."""
+        text = "" if text is None else str(text)
+        if self.rtl and not ltr and (ARABIC_RE.search(text) or kind in ("title", "subtitle", "h1", "h2")):
+            size, leading, color, bold, sb, sa = self.STYLES[kind]
+            if kind == "bullet":
+                text = "• " + text
+            return RTLParagraph(text, font="Amiri-Bold" if bold else "Amiri", size=size + 1, leading=leading * 1.25,
+                                color=color, align="center" if kind in ("title", "subtitle") else "right",
+                                space_before=sb, space_after=sa)
+        clean = escape(text.encode("latin-1", "replace").decode("latin-1"))
+        style = self._pstyles[kind]
+        if self.rtl and not ltr and kind != "bullet":  # numbers/English inside an Arabic table cell
+            style = ParagraphStyle(kind + "_r", parent=style, alignment=2)
+        if kind == "bullet":
+            return Paragraph(clean, style, bulletText="•")
+        return Paragraph(clean, style)
+
+    def table(self, rows, widths, header=True, zebra=True, bg=None):
+        if self.rtl:
+            rows = [list(reversed(r)) for r in rows]
+            widths = list(reversed(widths))
+        t = Table(rows, colWidths=widths, repeatRows=1 if header else 0)
+        style = [("VALIGN", (0, 0), (-1, -1), "TOP"), ("GRID", (0, 0), (-1, -1), 0.5, GRID),
+                 ("TOPPADDING", (0, 0), (-1, -1), 5), ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+                 ("LEFTPADDING", (0, 0), (-1, -1), 6), ("RIGHTPADDING", (0, 0), (-1, -1), 6)]
+        if header:
+            style.append(("BACKGROUND", (0, 0), (-1, 0), BRAND))
+        if bg is not None:
+            style.append(("BACKGROUND", (0, 1 if header else 0), (-1, -1), bg))
+        elif zebra:
+            style += [("BACKGROUND", (0, r), (-1, r), SOFT) for r in range(1 if header else 0, len(rows)) if r % 2 == 0]
+        t.setStyle(TableStyle(style))
+        return t
+
+
+def _chart_text(text: str, lang: str) -> str:
+    return _shape(text) if lang == "ar" and ARABIC_RE.search(text) else text
+
+
+def _chart_font(lang: str):
+    if lang != "ar":
+        return None
+    from matplotlib.font_manager import FontProperties
+    return FontProperties(fname=os.path.join(FONT_DIR, "Amiri-Regular.ttf"))
+
+
+def _fig_to_buffer(fig) -> io.BytesIO:
+    buf = io.BytesIO()
+    fig.tight_layout()
+    fig.savefig(buf, format="png", dpi=200)
+    plt.close(fig)
+    buf.seek(0)
+    return buf
+
+
+def _chart_scores(composite: Dict, lang: str) -> io.BytesIO:
+    fp = _chart_font(lang)
+    labels = [_chart_text(L(lang, k), lang) for k in ("confidence", "anxiety", "hesitation")]
+    values = [composite["confidence"], composite["anxiety"], composite["hesitation"]]
+    fig, ax = plt.subplots(figsize=(5.2, 2.6))
+    bars = ax.barh(labels, values, color=["#2E7D32", "#C62828", "#EF6C00"], height=0.55)
+    ax.set_xlim(0, 1)
+    ax.invert_yaxis()
+    if fp:
+        for lbl in ax.get_yticklabels():
+            lbl.set_fontproperties(fp)
+            lbl.set_fontsize(12)
+    for b, v in zip(bars, values):
+        ax.text(min(v + 0.02, 0.9), b.get_y() + b.get_height() / 2, f"{v:.2f}", va="center", fontsize=10)
+    ax.set_title(_chart_text(L(lang, "chart_vocal"), lang), fontsize=11 if not fp else 13, fontproperties=fp)
+    for s in ("top", "right"):
+        ax.spines[s].set_visible(False)
+    ax.grid(axis="x", alpha=0.3)
+    return _fig_to_buffer(fig)
+
+
+def _chart_talk_time(utterances: List[Dict], lang: str) -> io.BytesIO:
+    fp = _chart_font(lang)
+    totals: Dict[str, float] = {}
+    for u in utterances:
+        totals[u["role"]] = totals.get(u["role"], 0.0) + (u["end"] - u["start"]) / 1000
+    fig, ax = plt.subplots(figsize=(3.2, 2.6))
+    _, texts, _ = ax.pie(list(totals.values()), labels=[_chart_text(L(lang, r), lang) for r in totals],
+                         autopct="%1.0f%%", colors=["#1F6FEB", "#9DB9E8", "#CCCCCC"][: len(totals)],
+                         startangle=90, wedgeprops={"linewidth": 1, "edgecolor": "white"})
+    if fp:
+        for tx in texts:
+            tx.set_fontproperties(fp)
+            tx.set_fontsize(12)
+    ax.set_title(_chart_text(L(lang, "chart_talk"), lang), fontsize=11 if not fp else 13, fontproperties=fp)
+    return _fig_to_buffer(fig)
+
+
+def _chart_questions(qa: List[Dict], lang: str) -> Optional[io.BytesIO]:
+    scored = [q for q in qa if q.get("score") is not None]
+    if not scored:
+        return None
+    fp = _chart_font(lang)
+    fig, ax = plt.subplots(figsize=(6.6, 2.2))
+    xs = [f"Q{q['index']}" for q in scored]
+    ys = [q["score"] for q in scored]
+    cols = ["#2E7D32" if s >= 7 else "#EF6C00" if s >= 5 else "#C62828" for s in ys]
+    ax.bar(xs, ys, color=cols, width=0.6)
+    ax.set_ylim(0, 10)
+    for x, y in zip(xs, ys):
+        ax.text(x, y + 0.2, str(y), ha="center", fontsize=9)
+    ax.set_title(_chart_text(L(lang, "chart_q"), lang), fontsize=11 if not fp else 13, fontproperties=fp)
+    for s in ("top", "right"):
+        ax.spines[s].set_visible(False)
+    ax.grid(axis="y", alpha=0.3)
+    return _fig_to_buffer(fig)
+
+
+def create_pdf_report(analysis: Dict, output_path: str, lang: str = "en") -> None:
+    rb = ReportBuilder(lang)
+    lang = rb.lang
+    T, P = rb.t, rb.p
+    doc = SimpleDocTemplate(output_path, pagesize=letter, rightMargin=0.75 * inch, leftMargin=0.75 * inch,
+                            topMargin=0.9 * inch, bottomMargin=0.8 * inch,
+                            title="EvalBot Interview Analysis Report", author="EvalBot")
+    ev = analysis["evaluation"]
+    voice = analysis["voice_analysis"]
+    score = analysis["suitability_score"]
+    score_color = "#2E7D32" if score >= 65 else "#EF6C00" if score >= 50 else "#C62828"
+    W = doc.width
+    story: List = []
+
+    def bullets(items):
+        for it in items:
+            story.append(P(it, "bullet"))
+
+    def header_footer(canvas, d):
+        canvas.saveState()
+        top = letter[1] - 0.6 * inch
+        canvas.setStrokeColor(ACCENT)
+        canvas.setLineWidth(0.8)
+        canvas.line(d.leftMargin, top, letter[0] - d.rightMargin, top)
+        left_x, right_x = d.leftMargin, letter[0] - d.rightMargin
+        header = T("header")
+        footer = T("footer")
+        page = f"{T('page')} {d.page}"
+        if rb.rtl:
+            canvas.setFont("Amiri-Bold", 9.5)
+            canvas.setFillColor(BRAND)
+            canvas.drawRightString(right_x, top + 6, _shape(header))
+            canvas.setFont("Amiri", 9)
+            canvas.setFillColor(MUTED)
+            canvas.drawString(left_x, top + 6, analysis["generated_at"])
+            canvas.drawRightString(right_x, 0.5 * inch, _shape(footer))
+            canvas.drawString(left_x, 0.5 * inch, _shape(page))
+        else:
+            canvas.setFont("Helvetica-Bold", 8.5)
+            canvas.setFillColor(BRAND)
+            canvas.drawString(left_x, top + 6, header)
+            canvas.setFont("Helvetica", 8)
+            canvas.setFillColor(MUTED)
+            canvas.drawRightString(right_x, top + 6, analysis["generated_at"])
+            canvas.drawString(left_x, 0.5 * inch, footer)
+            canvas.drawRightString(right_x, 0.5 * inch, page)
+        canvas.restoreState()
+
+    # ---- Page 1: overview ------------------------------------------------------------
+    story += [Spacer(1, 0.25 * inch), P(T("report_title"), "title"), Spacer(1, 4),
+              P(f"{T('candidate_id')}: {analysis['user_id']}   |   {T('generated')}: {analysis['generated_at']}", "subtitle"),
+              Spacer(1, 0.3 * inch)]
+    num = Paragraph(f"<font size=30 color='{score_color}'><b>{score:.0f}</b></font>"
+                    f"<font size=12 color='#5B6573'> / 100</font>", ParagraphStyle("s", alignment=1, leading=36))
+    content = ev.get("content_score") if ev.get("content_score") is not None else "n/a"
+    detail = [P(T("suitability"), "tdb"), P(analysis["verdict"], "td"),
+              P(T("score_basis").format(content=content), "small")]
+    cells = [num, detail]
+    widths = [1.8 * inch, W - 1.8 * inch]
+    if rb.rtl:
+        cells, widths = cells[::-1], widths[::-1]
+    score_tbl = Table([cells], colWidths=widths)
+    score_tbl.setStyle(TableStyle([("BOX", (0, 0), (-1, -1), 1, GRID), ("BACKGROUND", (0, 0), (-1, -1), SOFT),
+                                   ("VALIGN", (0, 0), (-1, -1), "MIDDLE"), ("TOPPADDING", (0, 0), (-1, -1), 12),
+                                   ("BOTTOMPADDING", (0, 0), (-1, -1), 12), ("RIGHTPADDING", (0, 0), (-1, -1), 10)]))
+    story += [score_tbl, Spacer(1, 0.25 * inch)]
+
+    info = analysis["interview"]
+    rows = [[P(T("interview"), "th"), P("", "th")],
+            [P(T("duration"), "tdb"), P(f"{info['duration_seconds'] / 60:.1f} {T('minutes')}", "td")],
+            [P(T("speaker_turns"), "tdb"), P(str(info["speaker_turns"]), "td")],
+            [P(T("questions_answered"), "tdb"), P(str(len(analysis["qa_pairs"])), "td")],
+            [P(T("speakers"), "tdb"), P(" / ".join(f"{s['speaker_name']} ({T(s['role'])})"
+                                                 for s in analysis["speakers"].values()), "td")]]
+    if "error" not in voice:
+        rows.append([P(T("interviewee_time"), "tdb"),
+                     P(f"{voice['speaking_time_seconds'] / 60:.1f} {T('minutes')}, {voice['word_count']} {T('words')}", "td")])
+    story += [rb.table(rows, [2.3 * inch, W - 2.3 * inch]), Spacer(1, 0.2 * inch)]
+    story.append(P(T("exec_summary"), "h1"))
+    bullets(ev.get("executive_summary", []))
+    story.append(PageBreak())
+
+    # ---- Communication & vocal dynamics ------------------------------------------------
+    story.append(P(T("comm_title"), "h1"))
+    if "error" not in voice:
+        it = voice["interpretation"]
+        cs = voice["composite_scores"]
+        top_f = ", ".join(f"'{k}' x{v}" for k, v in list(voice["filler_words"].items())[:5]) or T("none")
+        mrows = [
+            [P(T("metric"), "th"), P(T("value"), "th"), P(T("meaning"), "th")],
+            [P(T("speaking_rate"), "tdb"), P(f"{voice['speaking_rate']:.2f} {T('wps')}", "td"), P(T("m_rate"), "td")],
+            [P(T("fillers"), "tdb"), P(f"{voice['filler_ratio'] * 100:.1f}% {T('of_words')}", "td"),
+             P(f"{T('most_frequent')}: {top_f}", "td")],
+            [P(T("repetition"), "tdb"), P(f"{voice['repetition_score']:.3f}", "td"), P(T("m_rep"), "td")],
+            [P(T("fluency"), "tdb"), P(T(it["fluency_level"]), "td"), P(T("m_flu"), "td")],
+            [P(T("confidence"), "tdb"), P(f"{T(it['confidence_level'])} ({cs['confidence']:.2f})", "td"), P(T("m_conf"), "td")],
+            [P(T("anxiety"), "tdb"), P(f"{T(it['anxiety_level'])} ({cs['anxiety']:.2f})", "td"), P(T("m_anx"), "td")],
+            [P(T("pitch"), "tdb"), P(f"{voice['pitch_analysis']['mean_hz']:.0f} Hz (sd {voice['pitch_analysis']['std_dev_hz']:.0f})", "td"),
+             P(T("m_pitch"), "td")],
+        ]
+        story += [rb.table(mrows, [1.5 * inch, 1.7 * inch, W - 3.2 * inch]), Spacer(1, 0.15 * inch)]
+        imgs = [Image(_chart_scores(cs, lang), width=3.9 * inch, height=1.95 * inch),
+                Image(_chart_talk_time(analysis["transcript"], lang), width=2.5 * inch, height=2.03 * inch)]
+        cw = [4.1 * inch, W - 4.1 * inch]
+        if rb.rtl:
+            imgs, cw = imgs[::-1], cw[::-1]
+        story += [Table([imgs], colWidths=cw), Spacer(1, 0.1 * inch)]
+    else:
+        story.append(P(voice["error"], "body"))
+    if ev.get("communication"):
+        story.append(P(T("observations"), "h2"))
+        bullets(ev["communication"])
+    if ev.get("communication_tip"):
+        story.append(P(T("tip"), "h2"))
+        story.append(P(ev["communication_tip"], "body"))
+
+    # ---- Question-by-question feedback --------------------------------------------------
+    qa = analysis["qa_pairs"]
+    if qa:
+        story.append(PageBreak())
+        story.append(P(T("qa_title"), "h1"))
+        chart = _chart_questions(qa, lang)
+        if chart:
+            story += [Image(chart, width=W, height=W * 2.2 / 6.6), Spacer(1, 0.1 * inch)]
+        for q in qa:
+            badge = f"{q['score']}/10" if q.get("score") is not None else ""
+            head_color = (colors.HexColor("#2E7D32") if (q.get("score") or 0) >= 7 else
+                          colors.HexColor("#EF6C00") if (q.get("score") or 0) >= 5 else colors.HexColor("#C62828"))
+            answer = q["answer"] if len(q["answer"]) < 420 else q["answer"][:400].rsplit(" ", 1)[0] + " ..."
+            rows = [[P(f"Q{q['index']}  {badge}", "th"), P(q["question"], "th", ltr=True)],
+                    [P(T("answer"), "tdb"), P(answer, "td", ltr=True)]]
+            if q.get("what_went_well"):
+                rows.append([P(T("went_well"), "tdb"), P(q["what_went_well"], "td")])
+            if q.get("what_to_improve"):
+                rows.append([P(T("to_improve"), "tdb"), P(q["what_to_improve"], "td")])
+            if q.get("improved_answer"):
+                rows.append([P(T("better_answer"), "tdb"), P(q["improved_answer"], "td", ltr=True)])
+            t = rb.table(rows, [1.35 * inch, W - 1.35 * inch], zebra=False)
+            t.setStyle(TableStyle([("BACKGROUND", (0, 0), (-1, 0), head_color)]))
+            if q.get("what_went_well"):
+                t.setStyle(TableStyle([("BACKGROUND", (0, 2), (-1, 2), GOOD_BG)]))
+            if q.get("what_to_improve"):
+                t.setStyle(TableStyle([("BACKGROUND", (0, 3), (-1, 3), BAD_BG)]))
+            story += [KeepTogether([t]), Spacer(1, 0.14 * inch)]
+
+    # ---- Competencies ------------------------------------------------------------------
+    if ev.get("strengths") or ev.get("weaknesses"):
+        story.append(PageBreak())
+        story.append(P(T("competency_title"), "h1"))
+    if ev.get("strengths"):
+        story.append(P(T("strengths"), "h2"))
+        rows = [[P(T("competency"), "th"), P(T("assessment"), "th")]]
+        for s in ev["strengths"]:
+            rows.append([P(s["competency"], "tdb"),
+                         [P(s["explanation"], "td"), P(f"{T('evidence')}: {s['evidence']}", "small")]])
+        story += [rb.table(rows, [1.7 * inch, W - 1.7 * inch], bg=GOOD_BG), Spacer(1, 0.15 * inch)]
+    if ev.get("weaknesses"):
+        story.append(P(T("dev_areas"), "h2"))
+        rows = [[P(T("area"), "th"), P(T("feedback"), "th")]]
+        rows += [[P(w["area"], "tdb"), P(w["feedback"], "td")] for w in ev["weaknesses"]]
+        story += [rb.table(rows, [1.7 * inch, W - 1.7 * inch], bg=BAD_BG), Spacer(1, 0.15 * inch)]
+
+    # ---- Role fit, recommendations, next steps -----------------------------------------
+    if ev.get("role_fit") or ev.get("recommendations") or ev.get("next_steps"):
+        story.append(PageBreak())
+    if ev.get("role_fit"):
+        story.append(P(T("role_fit"), "h1"))
+        bullets(ev["role_fit"])
+    if ev.get("recommendations"):
+        story.append(P(T("recs"), "h1"))
+        rows = [[P(T("rec_area"), "th"), P(T("recommendation"), "th"), P(T("how_to"), "th")]]
+        rows += [[P(T(r["category"]), "tdb"), P(r["recommendation"], "td"), P(r["how_to"], "td")]
+                 for r in ev["recommendations"]]
+        story += [rb.table(rows, [1.4 * inch, 2.6 * inch, W - 4.0 * inch]), Spacer(1, 0.15 * inch)]
+    if ev.get("next_steps"):
+        story.append(P(T("next_steps"), "h1"))
+        bullets(ev["next_steps"])
+
+    # ---- Appendix: transcript (always left-to-right, it's the original English) ----------
+    story.append(PageBreak())
+    story.append(P(T("appendix"), "h1"))
+    story.append(P(T("appendix_note"), "small"))
+    rows = [[P(T("time"), "th"), P(T("role"), "th"), P(T("text"), "th")]]
+    for u in analysis["transcript"]:
+        m, s = divmod(int(u["start"] / 1000), 60)
+        rows.append([P(f"{m:02d}:{s:02d}", "td"), P(T(u["role"]), "tdb"), P(u["text"], "td", ltr=True)])
+    story.append(rb.table(rows, [0.6 * inch, 1.0 * inch, W - 1.6 * inch]))
+    if not ev.get("ai_generated", True):
+        story += [Spacer(1, 0.2 * inch), P(T("ai_unavailable"), "small")]
+
+    doc.build(story, onFirstPage=header_footer, onLaterPages=header_footer)
+    logger.info("PDF report written to %s", output_path)
+
+
+# --------------------------------------------------------------------------------------
+# Main pipeline
+# --------------------------------------------------------------------------------------
+def convert_to_serializable(obj):
+    if isinstance(obj, np.generic):
+        return obj.item()
+    if isinstance(obj, np.ndarray):
+        return obj.tolist()
+    if isinstance(obj, dict):
+        return {k: convert_to_serializable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [convert_to_serializable(v) for v in obj]
+    return obj
+
+
+def process_interview(audio_path: str, user_id: str = "candidate", output_dir: str = OUTPUT_DIR,
+                      progress=None, lang: str = "en") -> Dict:
+    """Run the full pipeline. Returns paths to the PDF and JSON reports plus a short summary."""
+    lang = lang if lang in LABELS else "en"
+
+    def step(msg):
+        logger.info(msg)
+        if progress:
+            progress(msg)
+
+    wav_file = None
+    try:
+        step("Converting audio")
+        wav_file = convert_to_wav(audio_path)
+        y, sr = librosa.load(wav_file, sr=16000)
+
+        step("Transcribing with speaker diarization")
+        transcript = transcribe(wav_file)
+        utterances = transcript.get("utterances") or []
+        if not utterances:
+            raise ValueError("No speech was detected in the recording")
+
+        step("Extracting prosodic features")
+        for u in utterances:
+            u["prosodic_features"] = extract_prosodic_features(y, sr, u["start"], u["end"])
+
+        step("Identifying speakers")
+        speakers = identify_speakers(transcript, y, sr)
+
+        step("Classifying interviewer and interviewee")
+        roles = classify_roles(utterances)
+        for label, info in speakers.items():
+            info["role"] = roles.get(label, "Interviewee")
+        clean_utts = [{
+            "speaker": speakers[u["speaker"]]["speaker_name"], "label": u["speaker"],
+            "role": speakers[u["speaker"]]["role"], "start": u["start"], "end": u["end"], "text": u["text"],
+            "confidence": round(float(u.get("confidence", 0)), 3), "prosodic_features": u["prosodic_features"],
+        } for u in utterances]
+
+        step("Analyzing the interviewee's voice")
+        voice = analyze_interviewee_voice(y, sr, clean_utts)
+
+        analysis = {
+            "user_id": user_id, "language": lang,
+            "generated_at": time.strftime("%Y-%m-%d"),
+            "interview": {"duration_seconds": round(len(y) / sr, 1), "speaker_turns": len(clean_utts),
+                          "language": transcript.get("language_code", "en")},
+            "speakers": speakers, "voice_analysis": voice, "transcript": clean_utts,
+            "qa_pairs": build_qa_pairs(clean_utts),
+            "models": {
+                "transcription": "AssemblyAI universal-2",
+                "speaker_embeddings": "nvidia/speakerverification_en_titanet_large",
+                "speaker_index": "pinecone" if PINECONE_API_KEY else "built-in",
+                "role_classifier": "RandomForest (TF-IDF + handcrafted), trained on MIT interview transcripts",
+                "role_classifier_heldout_accuracy": getattr(get_role_classifier(), "heldout_accuracy_", None),
+                "evaluation": GEMINI_MODEL if GEMINI_API_KEY else None,
+            },
+        }
+
+        step("Generating AI evaluation")
+        evaluation = generate_evaluation(analysis, lang)
+        if evaluation is None:
+            evaluation = fallback_evaluation(analysis, lang)
+        else:
+            evaluation["ai_generated"] = True
+            by_index = {q.get("index"): q for q in evaluation.get("questions", [])}
+            for p in analysis["qa_pairs"]:
+                fb = by_index.get(p["index"], {})
+                p.update({k: fb.get(k) for k in ("score", "what_went_well", "what_to_improve", "improved_answer")})
+                if p.get("score") is not None:
+                    p["score"] = int(max(0, min(10, p["score"])))
+        evaluation.pop("questions", None)
+        analysis["evaluation"] = evaluation
+        provisional = evaluation.get("content_score") is None
+        analysis["suitability_score"] = calculate_acceptance_probability(voice, evaluation.get("content_score"))
+        analysis["verdict"] = verdict_for(analysis["suitability_score"], lang, provisional)
+
+        step("Building PDF report")
+        base = f"{user_id}_{uuid.uuid4().hex[:8]}"
+        os.makedirs(output_dir, exist_ok=True)
+        pdf_path = os.path.abspath(os.path.join(output_dir, f"{base}_report.pdf"))
+        json_path = os.path.abspath(os.path.join(output_dir, f"{base}_analysis.json"))
+        create_pdf_report(analysis, pdf_path, lang)
+        with open(json_path, "w", encoding="utf-8") as f:
+            json.dump(convert_to_serializable(analysis), f, indent=2, ensure_ascii=False)
+
+        step("Done")
+        return {"pdf_path": pdf_path, "json_path": json_path, "suitability_score": analysis["suitability_score"],
+                "verdict": analysis["verdict"], "summary": evaluation.get("executive_summary", []),
+                "voice": voice.get("interpretation", {}), "lang": lang}
+    finally:
+        if wav_file and os.path.exists(wav_file):
+            os.remove(wav_file)
+
+
+# --------------------------------------------------------------------------------------
+# Practice mode: one question, one recorded answer, instant feedback
+# --------------------------------------------------------------------------------------
+QUESTION_BANK = {
+    "General": [
+        "Tell me about yourself.",
+        "Why are you interested in this role?",
+        "Where do you see yourself in five years?",
+        "What are your greatest strengths?",
+        "What is your biggest weakness, and how are you working on it?",
+        "Why should we hire you?",
+    ],
+    "Behavioral": [
+        "Tell me about a time you faced a difficult challenge at work or university. How did you handle it?",
+        "Describe a situation where you disagreed with a teammate. What did you do?",
+        "Tell me about a time you made a mistake. What did you learn?",
+        "Give an example of a time you led a team or took initiative.",
+        "Describe a time you had to meet a tight deadline.",
+        "Tell me about a time you had to learn something new quickly.",
+    ],
+    "Data Engineering": [
+        "Explain the difference between batch and stream processing, and when you would use each.",
+        "How would you design a data pipeline that ingests data from several sources into a data warehouse?",
+        "What is the difference between a data lake and a data warehouse?",
+        "How do you make sure the data in your pipeline is accurate and of good quality?",
+        "Explain how Apache Spark processes data in a distributed way.",
+        "What role does Apache Kafka play in a real-time data architecture?",
+    ],
+    "Software Engineering": [
+        "How do you design a REST API that other teams will rely on?",
+        "Describe how you debug a problem that only happens in production.",
+        "What is the difference between a process and a thread?",
+        "How do you approach writing tests for your code?",
+        "Tell me about a technical decision you made and the trade-offs you considered.",
+        "How would you scale a web service that is getting slow under load?",
+    ],
+    "AI / Machine Learning": [
+        "Explain overfitting and how you prevent it.",
+        "How would you evaluate a classification model on an imbalanced dataset?",
+        "Walk me through a machine learning project you built from data to deployment.",
+        "What is the difference between supervised and unsupervised learning?",
+        "How would you explain a model's prediction to a non-technical stakeholder?",
+        "What are embeddings and where have you used them?",
+    ],
+}
+
+PRACTICE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "score": {"type": "integer", "description": "0-10 overall quality of the answer"},
+        "relevance": {"type": "string", "enum": ["on_topic", "partially", "off_topic"]},
+        "summary": {"type": "string"},
+        "strengths": {"type": "array", "items": {"type": "string"}},
+        "improvements": {"type": "array", "items": {"type": "string"}},
+        "delivery_tip": {"type": "string"},
+        "improved_answer": {"type": "string"},
+    },
+    "required": ["score", "relevance", "summary", "strengths", "improvements", "delivery_tip", "improved_answer"],
+}
+
+
+def generate_practice_questions(role: str, count: int = 5) -> List[str]:
+    role = (role or "").strip()[:80]
+    if not role:
+        return []
+    result = _gemini_json(
+        f"Write {count} realistic job interview questions for a candidate applying as: {role}.\n"
+        "Mix behavioral and role-specific technical questions, suitable for an entry-level to mid-level "
+        "candidate. Each question should be answerable in 1-2 minutes. Write them in English.",
+        {"type": "object", "properties": {"questions": {"type": "array", "items": {"type": "string"}}},
+         "required": ["questions"]}, temperature=0.8)
+    return [q.strip() for q in (result or {}).get("questions", []) if q.strip()][:count]
+
+
+def evaluate_practice_answer(audio_path: str, question: str, lang: str = "en", role: str = "") -> Dict:
+    lang = lang if lang in LABELS else "en"
+    wav_file = convert_to_wav(audio_path)
+    try:
+        y, sr = librosa.load(wav_file, sr=16000)
+        if len(y) < sr:
+            raise ValueError("The recording is too short. Please answer for at least a few seconds.")
+        transcript = transcribe(wav_file, speakers_expected=None, diarize=False)
+        words = transcript.get("words") or []
+        text = (transcript.get("text") or "").strip()
+        if not words or not text:
+            raise ValueError("No speech was detected. Check your microphone and try again.")
+        start, end = words[0]["start"], words[-1]["end"]
+        utt = {"role": "Interviewee", "start": start, "end": end, "text": text,
+               "prosodic_features": extract_prosodic_features(y, sr, start, end)}
+        voice = analyze_interviewee_voice(y, sr, [utt])
+        metrics = {k: voice.get(k) for k in ("speaking_rate", "filler_ratio", "filler_words", "interpretation")}
+        feedback = _gemini_json(
+            f"""You are an encouraging but honest interview coach. A candidate{f' applying for: {role}' if role else ''}
+answered one interview question out loud. Evaluate the answer.
+
+- Judge relevance, structure (e.g. STAR), specificity and impact. Be concrete and kind.
+- 2-4 strengths and 2-4 improvements, each one sentence.
+- delivery_tip: one tip based on the voice metrics (pace, filler words, confidence).
+- improved_answer: a stronger version (4-6 sentences, first person) that keeps the candidate's own facts;
+  use placeholders like [number] where a detail is missing. Keep it in English.
+{_language_rule(lang)}
+Question: {question}
+Answer (transcribed): {text}
+Answer length: {(end - start) / 1000:.0f} seconds
+Voice metrics: {json.dumps(metrics)}
+""", PRACTICE_SCHEMA)
+        if feedback:
+            feedback["score"] = int(max(0, min(10, feedback.get("score", 0))))
+            feedback["ai_generated"] = True
+        else:
+            feedback = {"ai_generated": False, "score": None, "summary": fallback_evaluation(
+                {"voice_analysis": voice}, lang)["communication"][0] if "error" not in voice else "",
+                "strengths": [], "improvements": [], "delivery_tip": "", "improved_answer": "", "relevance": None}
+        return {"question": question, "transcript": text, "duration_seconds": round((end - start) / 1000, 1),
+                "voice": voice, "feedback": feedback, "lang": lang}
+    finally:
+        if os.path.exists(wav_file):
+            os.remove(wav_file)
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 2:
+        print("usage: python process_interview.py <audio-file> [user_id] [en|ar]")
+        sys.exit(1)
+    out = process_interview(sys.argv[1], sys.argv[2] if len(sys.argv) > 2 else "candidate",
+                            lang=sys.argv[3] if len(sys.argv) > 3 else "en")
+    print(json.dumps(out, indent=2, ensure_ascii=False))

requirements.txt

@@ -0,0 +1,28 @@
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch==2.2.2
+torchaudio==2.2.2
+numpy==1.24.4
+setuptools<70
+nemo_toolkit[asr]==1.23.0
+pytorch-lightning==2.0.7
+huggingface_hub==0.23.2
+cloudpickle==2.2.1
+datasets==3.2.0
+pyarrow==25.0.1
+fsspec==2024.9.0
+pinecone
+google-genai
+librosa
+soundfile
+pydub
+scikit-learn==1.7.2
+pandas
+joblib==1.5.3
+reportlab
+matplotlib
+fastapi
+uvicorn[standard]
+python-multipart
+requests
+arabic-reshaper
+python-bidi

static_ui.html

@@ -0,0 +1,557 @@
+<!doctype html>
+<html lang="en" dir="ltr">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>EvalBot · AI Interview Analysis</title>
+<style>
+  :root {
+    --bg:#f4f6fa; --card:#fff; --ink:#152033; --muted:#5b6573; --line:#dde4ee; --soft:#eef3fb;
+    --brand:#0b3d91; --accent:#1f6feb; --accent-ink:#fff; --good:#2e7d32; --good-bg:#eaf6ec;
+    --mid:#ef6c00; --mid-bg:#fff3e6; --bad:#c62828; --bad-bg:#fdeeee; --hl:#fff7d6; --shadow:0 1px 2px rgba(16,24,40,.05);
+  }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg:#0e1420; --card:#161e2c; --ink:#e7ecf4; --muted:#9aa6b8; --line:#2a3548; --soft:#1c2738;
+      --brand:#8fb4ff; --accent:#4c8dff; --good:#5cc06a; --good-bg:#16301d; --mid:#ffa24c; --mid-bg:#33240f;
+      --bad:#ff6b6b; --bad-bg:#3a1919; --hl:#3a3313; --shadow:none; }
+  }
+  * { box-sizing:border-box; }
+  html { -webkit-text-size-adjust:100%; }
+  body { margin:0; font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans Arabic", Tahoma, sans-serif;
+         background:var(--bg); color:var(--ink); line-height:1.5; }
+  main { max-width: 860px; margin:0 auto; padding: 24px 16px 64px; }
+  header { display:flex; justify-content:space-between; align-items:flex-start; gap:12px; flex-wrap:wrap; }
+  h1 { margin:0; font-size:28px; color:var(--brand); letter-spacing:-.01em; }
+  .tagline { color:var(--muted); margin:4px 0 0; }
+  .lang { display:flex; border:1px solid var(--line); border-radius:999px; overflow:hidden; background:var(--card); }
+  .lang button { border:0; background:none; padding:6px 14px; cursor:pointer; color:var(--muted); font:inherit; font-size:14px; }
+  .lang button.on { background:var(--accent); color:var(--accent-ink); }
+  .tabs { display:flex; gap:6px; margin:20px 0 14px; border-bottom:1px solid var(--line); }
+  .tabs button { border:0; background:none; padding:10px 14px; font:inherit; font-weight:600; color:var(--muted); cursor:pointer;
+                 border-bottom:3px solid transparent; margin-bottom:-1px; }
+  .tabs button.on { color:var(--accent); border-color:var(--accent); }
+  .card { background:var(--card); border:1px solid var(--line); border-radius:14px; padding:18px; margin-bottom:14px; box-shadow:var(--shadow); }
+  .card h2 { font-size:17px; margin:0 0 12px; color:var(--brand); }
+  .card h3 { font-size:15px; margin:16px 0 8px; }
+  .drop { border:2px dashed var(--line); border-radius:12px; padding:24px; text-align:center; cursor:pointer; transition:.15s; }
+  .drop.over, .drop:hover { border-color:var(--accent); background:var(--soft); }
+  .drop strong { color:var(--accent); }
+  .hint { color:var(--muted); font-size:13px; }
+  label { font-size:14px; color:var(--muted); display:block; margin-bottom:4px; }
+  input[type=text], select { width:100%; padding:10px 12px; border:1px solid var(--line); border-radius:9px; font:inherit; font-size:15px;
+                             background:var(--card); color:var(--ink); }
+  .row { display:flex; gap:10px; flex-wrap:wrap; align-items:flex-end; }
+  .row > * { flex:1 1 200px; }
+  .btn { background:var(--accent); color:var(--accent-ink); border:0; border-radius:9px; padding:11px 16px; font:inherit; font-size:15px;
+         font-weight:600; cursor:pointer; display:inline-flex; align-items:center; justify-content:center; gap:8px; }
+  .btn.ghost { background:none; color:var(--accent); border:1px solid var(--accent); }
+  .btn.rec { background:var(--bad); }
+  .btn:disabled { opacity:.5; cursor:default; }
+  .btns { display:flex; gap:10px; flex-wrap:wrap; margin-top:14px; }
+  .btns .btn { flex:1 1 180px; }
+  .steps { list-style:none; padding:0; margin:6px 0 0; }
+  .steps li { padding:5px 0; color:var(--muted); display:flex; gap:10px; align-items:center; }
+  .steps li::before { width:18px; text-align:center; }
+  .steps li.done { color:var(--ink); } .steps li.done::before { content:"✓"; color:var(--good); font-weight:700; }
+  .steps li.active { color:var(--ink); font-weight:600; } .steps li.active::before { content:"●"; color:var(--accent); animation:pulse 1s infinite; }
+  .steps li.todo::before { content:"○"; }
+  @keyframes pulse { 50% { opacity:.3 } }
+  .score-wrap { display:flex; gap:18px; align-items:center; flex-wrap:wrap; }
+  .ring { width:110px; height:110px; flex:none; }
+  .ring text { font-weight:800; fill:var(--ink); }
+  .verdict { font-weight:600; }
+  .chips { display:flex; gap:8px; flex-wrap:wrap; margin-top:10px; }
+  .chip { background:var(--soft); border:1px solid var(--line); border-radius:999px; padding:3px 11px; font-size:13px; }
+  .bars { display:grid; gap:10px; }
+  .bar { display:grid; grid-template-columns: 110px 1fr 46px; gap:10px; align-items:center; font-size:14px; }
+  .bar .track { height:10px; background:var(--soft); border-radius:99px; overflow:hidden; }
+  .bar .fill { height:100%; border-radius:99px; }
+  .metrics { display:grid; grid-template-columns: repeat(auto-fit, minmax(150px,1fr)); gap:10px; margin-top:14px; }
+  .metric { background:var(--soft); border-radius:10px; padding:10px 12px; }
+  .metric b { display:block; font-size:18px; }
+  .metric span { color:var(--muted); font-size:13px; }
+  details.q { border:1px solid var(--line); border-radius:11px; margin-bottom:10px; background:var(--card); }
+  details.q summary { list-style:none; cursor:pointer; padding:12px 14px; display:flex; gap:12px; align-items:flex-start; }
+  details.q summary::-webkit-details-marker { display:none; }
+  .badge { flex:none; font-weight:700; font-size:13px; border-radius:8px; padding:3px 8px; color:#fff; min-width:48px; text-align:center; }
+  .qbody { padding:0 14px 14px; display:grid; gap:10px; }
+  .box { border-radius:9px; padding:10px 12px; font-size:14px; }
+  .box h4 { margin:0 0 4px; font-size:13px; text-transform:uppercase; letter-spacing:.03em; color:var(--muted); }
+  .box.good { background:var(--good-bg); } .box.bad { background:var(--bad-bg); } .box.plain { background:var(--soft); }
+  .en { direction:ltr; text-align:left; unicode-bidi:isolate; }
+  ul.list { margin:0; padding-inline-start:20px; }
+  ul.list li { margin:4px 0; }
+  .two { display:grid; grid-template-columns: 1fr 1fr; gap:12px; }
+  @media (max-width: 640px) { .two { grid-template-columns:1fr; } .bar { grid-template-columns: 90px 1fr 40px; } }
+  .player { position:sticky; top:0; background:var(--card); padding:8px 0; z-index:2; }
+  audio { width:100%; }
+  .tx { max-height:420px; overflow:auto; border:1px solid var(--line); border-radius:10px; }
+  .line { display:grid; grid-template-columns: 52px 92px 1fr; gap:8px; padding:8px 10px; border-bottom:1px solid var(--line); cursor:pointer; font-size:14px; }
+  .line:hover { background:var(--soft); }
+  .line.now { background:var(--hl); }
+  .line .t { color:var(--muted); font-variant-numeric:tabular-nums; }
+  .line .r { font-weight:600; }
+  .line .r.Interviewer { color:var(--accent); } .line .r.Interviewee { color:var(--good); }
+  .downloads { display:flex; gap:10px; flex-wrap:wrap; }
+  .downloads a { flex:1 1 180px; text-align:center; text-decoration:none; padding:10px; border-radius:9px; border:1px solid var(--accent);
+                 color:var(--accent); font-weight:600; }
+  .downloads a.primary { background:var(--accent); color:var(--accent-ink); }
+  .qcard { background:var(--soft); border-radius:12px; padding:16px; font-size:18px; font-weight:600; }
+  .qmeta { display:flex; gap:8px; margin-top:10px; flex-wrap:wrap; }
+  .timer { font-variant-numeric:tabular-nums; font-weight:700; }
+  .err { color:var(--bad); white-space:pre-wrap; }
+  .hidden { display:none !important; }
+  .session { font-size:14px; }
+  .session li { display:flex; justify-content:space-between; gap:10px; }
+  footer { color:var(--muted); font-size:13px; margin-top:28px; }
+  code { background:var(--soft); padding:1px 5px; border-radius:4px; font-size:12.5px; }
+  .sr { position:absolute; left:-9999px; }
+</style>
+</head>
+<body>
+<main>
+  <header>
+    <div>
+      <h1>EvalBot</h1>
+      <p class="tagline" data-i="tagline"></p>
+    </div>
+    <div class="lang" role="group" aria-label="Language">
+      <button data-lang="en" class="on">English</button><button data-lang="ar">العربية</button>
+    </div>
+  </header>
+
+  <nav class="tabs" role="tablist">
+    <button data-tab="analyze" class="on" data-i="tab_analyze"></button>
+    <button data-tab="practice" data-i="tab_practice"></button>
+  </nav>
+
+  <!-- ============ ANALYZE ============ -->
+  <section id="analyze">
+    <div class="card" id="form-card">
+      <div class="drop" id="drop" tabindex="0">
+        <div><strong data-i="choose"></strong> <span data-i="or_drag"></span></div>
+        <div class="hint" data-i="formats"></div>
+        <div id="fname" style="margin-top:8px;font-weight:600"></div>
+        <input type="file" id="file" accept="audio/*,video/mp4,video/webm" hidden>
+      </div>
+      <div style="margin-top:12px">
+        <label for="uid" data-i="cand_id"></label>
+        <input type="text" id="uid" placeholder="candidate_42">
+      </div>
+      <div class="btns">
+        <button class="btn" id="go" disabled data-i="analyze_btn"></button>
+        <button class="btn ghost" id="sample" data-i="sample_btn"></button>
+      </div>
+      <p class="hint" data-i="sample_note" style="margin:10px 0 0"></p>
+    </div>
+
+    <div class="card hidden" id="progress-card">
+      <strong data-i="analyzing"></strong> <span class="hint" data-i="takes"></span>
+      <ul class="steps" id="steps"></ul>
+    </div>
+
+    <div id="results" class="hidden"></div>
+  </section>
+
+  <!-- ============ PRACTICE ============ -->
+  <section id="practice" class="hidden">
+    <div class="card">
+      <h2 data-i="p_title"></h2>
+      <p class="hint" data-i="p_intro" style="margin-top:-6px"></p>
+      <div class="row">
+        <div><label for="cat" data-i="category"></label><select id="cat"></select></div>
+        <div><label for="role" data-i="or_role"></label><input type="text" id="role" data-ph="role_ph"></div>
+      </div>
+      <div class="btns" style="margin-top:10px"><button class="btn ghost" id="gen" data-i="gen_btn"></button></div>
+    </div>
+
+    <div class="card">
+      <div class="qcard en" id="qtext"></div>
+      <div class="qmeta">
+        <button class="btn ghost" id="speak" data-i="listen"></button>
+        <button class="btn ghost" id="nextq" data-i="next_q"></button>
+      </div>
+      <div class="btns">
+        <button class="btn rec" id="recbtn"><span id="recl" data-i="record"></span> <span class="timer" id="timer"></span></button>
+      </div>
+      <audio id="myans" controls class="hidden" style="margin-top:12px"></audio>
+      <div class="btns"><button class="btn" id="fb" disabled data-i="get_fb"></button></div>
+      <p class="hint" id="pstatus" style="margin:10px 0 0"></p>
+    </div>
+
+    <div id="presult" class="hidden"></div>
+
+    <div class="card hidden" id="session-card">
+      <h2 data-i="session"></h2>
+      <ul class="list session" id="session"></ul>
+    </div>
+  </section>
+
+  <footer>
+    <span data-i="pipeline"></span><br>
+    API: <code>POST /process-audio</code>, <code>POST /practice</code>. <span data-i="credit"></span>
+  </footer>
+</main>
+
+<script>
+const I18N = {
+  en: {
+    tagline: "AI interview analysis: upload a recorded interview, or practice answering questions out loud.",
+    tab_analyze: "Analyze an interview", tab_practice: "Practice mode",
+    choose: "Choose an audio file", or_drag: "or drag it here",
+    formats: "WAV, MP3, M4A, FLAC, OGG, WEBM · English · up to 100 MB",
+    cand_id: "Candidate ID (optional)", analyze_btn: "Analyze interview", sample_btn: "Try a sample interview",
+    sample_note: "The sample is a 2-minute mock interview for a data engineering role, voiced with text-to-speech.",
+    analyzing: "Analyzing…", takes: "usually 1-2 minutes",
+    steps: ["Converting audio","Transcribing with speaker diarization","Extracting prosodic features","Identifying speakers",
+            "Classifying interviewer and interviewee","Analyzing the interviewee's voice","Generating AI evaluation","Building PDF report"],
+    suitability: "Suitability score", content: "Content", delivery: "Delivery",
+    confidence: "Confidence", anxiety: "Anxiety", hesitation: "Hesitation", fluency: "Fluency",
+    high: "high", moderate: "moderate", low: "low", fluent: "fluent", disfluent: "disfluent",
+    voice: "Voice & delivery", rate: "Speaking rate", wps: "words/sec", fillers: "Filler words", talk: "Candidate talk time",
+    min: "min", words: "words", summary: "Summary", qa: "Question by question", answer: "Answer",
+    went_well: "What went well", improve: "What to improve", better: "A stronger answer",
+    strengths: "Strengths", weaknesses: "Development areas", evidence: "Evidence",
+    recs: "Recommendations", transcript: "Transcript", tx_hint: "Click a line to jump to that moment.",
+    pdf: "Open PDF report", json: "Download JSON", again: "Analyze another interview",
+    Interviewer: "Interviewer", Interviewee: "Candidate",
+    p_title: "Practice an interview answer",
+    p_intro: "Pick a question, listen to it, record your answer, and get instant feedback on what you said and how you said it.",
+    category: "Question category", or_role: "…or generate questions for a role", role_ph: "e.g. Junior Data Engineer",
+    gen_btn: "Generate questions for this role", listen: "🔊 Listen", next_q: "Next question",
+    record: "● Record answer", stop: "■ Stop", rerecord: "● Record again", get_fb: "Get feedback",
+    p_eval: "Evaluating your answer…", mic_err: "Microphone access is needed to record. Allow it in your browser and try again.",
+    p_score: "Answer score", relevance: {on_topic: "On topic", partially: "Partly on topic", off_topic: "Off topic"},
+    you_said: "What you said", tip: "Delivery tip", session: "This session", gen_fail: "Couldn't generate questions right now.",
+    pipeline: "Pipeline: AssemblyAI transcription & diarization · NVIDIA NeMo TitaNet speaker embeddings + vector index · Random Forest role classifier trained on the MIT Interview dataset · librosa voice analysis · Gemini evaluation · ReportLab PDF.",
+    credit: "EvalBot graduation project, Benha University.",
+    wrong: "Something went wrong", provisional: "provisional",
+  },
+  ar: {
+    tagline: "تحليل المقابلات بالذكاء الاصطناعي: ارفع تسجيل مقابلة، أو تدرّب على الإجابة بصوتك.",
+    tab_analyze: "تحليل مقابلة", tab_practice: "وضع التدريب",
+    choose: "اختر ملفاً صوتياً", or_drag: "أو اسحبه هنا",
+    formats: "WAV، MP3، M4A، FLAC، OGG، WEBM · المقابلة بالإنجليزية · حتى 100 ميجابايت",
+    cand_id: "رقم المرشّح (اختياري)", analyze_btn: "حلّل المقابلة", sample_btn: "جرّب مقابلة نموذجية",
+    sample_note: "المقابلة النموذجية مدتها دقيقتان لوظيفة مهندس بيانات، بأصوات مولّدة آلياً.",
+    analyzing: "جارٍ التحليل…", takes: "عادةً من دقيقة إلى دقيقتين",
+    steps: ["تحويل الصوت","تحويل الكلام إلى نص وتمييز المتحدثين","استخراج خصائص الصوت","التعرّف على المتحدثين",
+            "تحديد المحاوِر والمرشّح","تحليل صوت المرشّح","التقييم بالذكاء الاصطناعي","إنشاء تقرير PDF"],
+    suitability: "درجة الملاءمة", content: "المحتوى", delivery: "الأداء",
+    confidence: "الثقة", anxiety: "القلق", hesitation: "التردد", fluency: "الطلاقة",
+    high: "مرتفع", moderate: "متوسط", low: "منخفض", fluent: "طليق", disfluent: "متقطع",
+    voice: "الصوت والأداء", rate: "معدل الكلام", wps: "كلمة/ثانية", fillers: "كلمات الحشو", talk: "مدة كلام المرشّح",
+    min: "دقيقة", words: "كلمة", summary: "الملخص", qa: "تقييم كل سؤال", answer: "الإجابة",
+    went_well: "ما كان جيداً", improve: "ما يحتاج إلى تحسين", better: "إجابة أقوى",
+    strengths: "نقاط القوة", weaknesses: "مجالات التطوير", evidence: "الدليل",
+    recs: "التوصيات", transcript: "نص المقابلة", tx_hint: "اضغط على أي سطر للانتقال إلى تلك اللحظة.",
+    pdf: "افتح تقرير PDF", json: "تحميل JSON", again: "حلّل مقابلة أخرى",
+    Interviewer: "المحاوِر", Interviewee: "المرشّح",
+    p_title: "تدرّب على الإجابة",
+    p_intro: "اختر سؤالاً واستمع إليه، ثم سجّل إجابتك بالإنجليزية، وستحصل فوراً على تقييم لما قلته وطريقة قوله.",
+    category: "نوع الأسئلة", or_role: "…أو ولّد أسئلة لوظيفة معينة", role_ph: "مثال: Junior Data Engineer",
+    gen_btn: "ولّد أسئلة لهذه الوظيفة", listen: "🔊 استمع", next_q: "السؤال التالي",
+    record: "● سجّل إجابتك", stop: "■ إيقاف", rerecord: "● سجّل مرة أخرى", get_fb: "قيّم إجابتي",
+    p_eval: "جارٍ تقييم إجابتك…", mic_err: "يجب السماح باستخدام الميكروفون للتسجيل. اسمح به من المتصفح ثم حاول مرة أخرى.",
+    p_score: "درجة الإجابة", relevance: {on_topic: "مرتبطة بالسؤال", partially: "مرتبطة جزئياً", off_topic: "خارج الموضوع"},
+    you_said: "ما قلته", tip: "نصيحة للأداء", session: "هذه الجلسة", gen_fail: "تعذّر توليد الأسئلة الآن.",
+    pipeline: "المكوّنات: AssemblyAI لتحويل الكلام وتمييز المتحدثين · NVIDIA NeMo TitaNet لبصمة الصوت مع فهرس متجهات · Random Forest لتحديد الأدوار مدرّب على بيانات MIT Interview · librosa لتحليل الصوت · Gemini للتقييم · ReportLab للتقرير.",
+    credit: "مشروع تخرج EvalBot، جامعة بنها.",
+    wrong: "حدث خطأ", provisional: "مبدئي",
+  }
+};
+let lang = "en";
+try { lang = localStorage.getItem("evalbot_lang") || (navigator.language || "").startsWith("ar") && "ar" || "en"; } catch (e) {}
+const $ = id => document.getElementById(id);
+const t = k => (I18N[lang][k] ?? I18N.en[k] ?? k);
+const esc = s => String(s ?? "").replace(/[&<>"]/g, c => ({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;"}[c]));
+const fmtTime = ms => { const s = Math.floor(ms / 1000); return String(Math.floor(s / 60)).padStart(2, "0") + ":" + String(s % 60).padStart(2, "0"); };
+const tone = (v, hi, mid) => v >= hi ? "var(--good)" : v >= mid ? "var(--mid)" : "var(--bad)";
+
+function applyLang() {
+  document.documentElement.lang = lang;
+  document.documentElement.dir = lang === "ar" ? "rtl" : "ltr";
+  document.querySelectorAll("[data-i]").forEach(el => el.textContent = t(el.dataset.i));
+  document.querySelectorAll("[data-ph]").forEach(el => el.placeholder = t(el.dataset.ph));
+  document.querySelectorAll(".lang button").forEach(b => b.classList.toggle("on", b.dataset.lang === lang));
+  if (lastAnalysis) renderResults(lastAnalysis, lastMeta);
+  if (lastPractice) renderPractice(lastPractice);
+  if (recState === "recorded") $("recl").textContent = t("rerecord");
+}
+document.querySelectorAll(".lang button").forEach(b => b.onclick = () => {
+  lang = b.dataset.lang; try { localStorage.setItem("evalbot_lang", lang); } catch (e) {}
+  applyLang();
+});
+document.querySelectorAll(".tabs button").forEach(b => b.onclick = () => {
+  document.querySelectorAll(".tabs button").forEach(x => x.classList.toggle("on", x === b));
+  $("analyze").classList.toggle("hidden", b.dataset.tab !== "analyze");
+  $("practice").classList.toggle("hidden", b.dataset.tab !== "practice");
+});
+
+/* ---------------- Analyze ---------------- */
+let chosen = null, audioUrl = null, lastAnalysis = null, lastMeta = null;
+const drop = $("drop"), input = $("file");
+drop.onclick = () => input.click();
+drop.onkeydown = e => { if (e.key === "Enter" || e.key === " ") input.click(); };
+input.onchange = () => pick(input.files[0]);
+drop.ondragover = e => { e.preventDefault(); drop.classList.add("over"); };
+drop.ondragleave = () => drop.classList.remove("over");
+drop.ondrop = e => { e.preventDefault(); drop.classList.remove("over"); pick(e.dataTransfer.files[0]); };
+function pick(f) { if (!f) return; chosen = f; $("fname").textContent = f.name + " (" + (f.size / 1048576).toFixed(1) + " MB)"; $("go").disabled = false; }
+
+function renderSteps(current, done) {
+  const steps = I18N[lang].steps, idx = I18N.en.steps.indexOf(current);
+  $("steps").innerHTML = steps.map((s, i) => `<li class="${done || (idx >= 0 && i < idx) ? "done" : i === idx ? "active" : "todo"}">${s}</li>`).join("");
+}
+async function start(useSample) {
+  $("go").disabled = $("sample").disabled = true;
+  $("results").classList.add("hidden");
+  $("progress-card").classList.remove("hidden");
+  renderSteps("", false);
+  const fd = new FormData();
+  if (useSample) { fd.append("sample", "true"); audioUrl = "sample.mp3"; }
+  else { fd.append("file", chosen); if (audioUrl && audioUrl.startsWith("blob:")) URL.revokeObjectURL(audioUrl); audioUrl = URL.createObjectURL(chosen); }
+  fd.append("user_id", $("uid").value || (useSample ? "sample_candidate" : "candidate"));
+  fd.append("lang", lang);
+  try {
+    const r = await fetch("jobs", { method: "POST", body: fd });
+    const j = await r.json();
+    if (!r.ok) throw new Error(j.detail || "Upload failed");
+    poll(j.job_id);
+  } catch (e) { fail(e.message); }
+}
+$("go").onclick = () => start(false);
+$("sample").onclick = () => start(true);
+
+async function poll(id) {
+  try {
+    const r = await fetch("jobs/" + id), j = await r.json();
+    if (j.status === "done") {
+      const a = await (await fetch(j.result.json_path.replace(/^\//, ""))).json();
+      lastAnalysis = a; lastMeta = j.result;
+      $("progress-card").classList.add("hidden");
+      renderResults(a, j.result);
+      $("go").disabled = !chosen; $("sample").disabled = false;
+      $("results").scrollIntoView({ behavior: "smooth" });
+      return;
+    }
+    if (j.status === "error") return fail(j.error);
+    renderSteps(j.step, false);
+  } catch (e) { /* transient network error: keep polling */ }
+  setTimeout(() => poll(id), 2000);
+}
+function fail(msg) {
+  $("progress-card").classList.add("hidden");
+  $("results").innerHTML = `<div class="card"><strong>${t("wrong")}</strong><p class="err">${esc(msg)}</p></div>`;
+  $("results").classList.remove("hidden");
+  $("go").disabled = !chosen; $("sample").disabled = false;
+}
+
+function ring(score) {
+  const r = 46, c = 2 * Math.PI * r, v = Math.max(0, Math.min(100, score));
+  return `<svg class="ring" viewBox="0 0 110 110" role="img" aria-label="${Math.round(v)} / 100">
+    <circle cx="55" cy="55" r="${r}" fill="none" stroke="var(--soft)" stroke-width="10"/>
+    <circle cx="55" cy="55" r="${r}" fill="none" stroke="${tone(v, 65, 50)}" stroke-width="10" stroke-linecap="round"
+      stroke-dasharray="${c * v / 100} ${c}" transform="rotate(-90 55 55)"/>
+    <text x="55" y="62" text-anchor="middle" font-size="28">${Math.round(v)}</text></svg>`;
+}
+function bar(label, v, color) {
+  return `<div class="bar"><span>${label}</span><div class="track"><div class="fill" style="width:${Math.round(v * 100)}%;background:${color}"></div></div><span>${v.toFixed(2)}</span></div>`;
+}
+function scoreBadge(s, max = 10) {
+  if (s == null) return "";
+  const c = s / max >= .7 ? "var(--good)" : s / max >= .5 ? "var(--mid)" : "var(--bad)";
+  return `<span class="badge" style="background:${c}">${s}/${max}</span>`;
+}
+
+function renderResults(a, meta) {
+  const ev = a.evaluation || {}, v = a.voice_analysis || {}, it = v.interpretation || {}, cs = v.composite_scores || {};
+  const dir = (a.language === "ar") ? "rtl" : "ltr";
+  const L = s => `<span dir="${dir}">${esc(s)}</span>`;
+  let h = "";
+  h += `<div class="card"><div class="score-wrap">${ring(a.suitability_score)}
+        <div style="flex:1 1 240px"><div class="hint">${t("suitability")}</div>
+        <div class="verdict">${L(a.verdict)}</div>
+        <div class="chips">
+          ${ev.content_score != null ? `<span class="chip">${t("content")}: ${ev.content_score}/100</span>` : `<span class="chip">${t("provisional")}</span>`}
+          ${it.confidence_level ? `<span class="chip">${t("confidence")}: ${t(it.confidence_level)}</span>` : ""}
+          ${it.anxiety_level ? `<span class="chip">${t("anxiety")}: ${t(it.anxiety_level)}</span>` : ""}
+          ${it.fluency_level ? `<span class="chip">${t("fluency")}: ${t(it.fluency_level)}</span>` : ""}
+        </div></div></div>
+      <div class="downloads" style="margin-top:16px"><a class="primary" href="${meta.pdf_path.replace(/^\//, "")}" target="_blank" rel="noopener">${t("pdf")}</a>
+        <a href="${meta.json_path.replace(/^\//, "")}" target="_blank" rel="noopener">${t("json")}</a></div></div>`;
+
+  if ((ev.executive_summary || []).length)
+    h += `<div class="card"><h2>${t("summary")}</h2><ul class="list" dir="${dir}">${ev.executive_summary.map(x => `<li>${esc(x)}</li>`).join("")}</ul></div>`;
+
+  if (!v.error) {
+    const fl = Object.entries(v.filler_words || {}).slice(0, 4).map(([k, n]) => `"${k}" ×${n}`).join(", ");
+    h += `<div class="card"><h2>${t("voice")}</h2><div class="bars">
+        ${bar(t("confidence"), cs.confidence, "var(--good)")}${bar(t("anxiety"), cs.anxiety, "var(--bad)")}${bar(t("hesitation"), cs.hesitation, "var(--mid)")}</div>
+      <div class="metrics">
+        <div class="metric"><b>${v.speaking_rate}</b><span>${t("rate")} (${t("wps")})</span></div>
+        <div class="metric"><b>${(v.filler_ratio * 100).toFixed(1)}%</b><span>${t("fillers")}${fl ? " · " + esc(fl) : ""}</span></div>
+        <div class="metric"><b>${(v.speaking_time_seconds / 60).toFixed(1)} ${t("min")}</b><span>${t("talk")} · ${v.word_count} ${t("words")}</span></div>
+      </div>
+      ${ev.communication_tip ? `<div class="box plain" style="margin-top:12px" dir="${dir}">💡 ${esc(ev.communication_tip)}</div>` : ""}</div>`;
+  }
+
+  if ((a.qa_pairs || []).length) {
+    h += `<div class="card"><h2>${t("qa")}</h2>` + a.qa_pairs.map((q, i) => `
+      <details class="q" ${i === 0 ? "open" : ""}><summary>${scoreBadge(q.score) || `<span class="badge" style="background:var(--muted)">Q${q.index}</span>`}
+        <span class="en">${esc(q.question)}</span></summary>
+        <div class="qbody">
+          <div class="box plain"><h4>${t("answer")} · <a href="#" data-seek="${q.answer_start}">${fmtTime(q.answer_start)}</a></h4><div class="en">${esc(q.answer)}</div></div>
+          ${q.what_went_well ? `<div class="box good"><h4>${t("went_well")}</h4><div dir="${dir}">${esc(q.what_went_well)}</div></div>` : ""}
+          ${q.what_to_improve ? `<div class="box bad"><h4>${t("improve")}</h4><div dir="${dir}">${esc(q.what_to_improve)}</div></div>` : ""}
+          ${q.improved_answer ? `<div class="box plain"><h4>${t("better")}</h4><div class="en">${esc(q.improved_answer)}</div></div>` : ""}
+        </div></details>`).join("") + `</div>`;
+  }
+
+  if ((ev.strengths || []).length || (ev.weaknesses || []).length) {
+    h += `<div class="card two"><div><h2>${t("strengths")}</h2>${(ev.strengths || []).map(s => `<div class="box good" style="margin-bottom:8px" dir="${dir}">
+          <b>${esc(s.competency)}</b><div>${esc(s.explanation)}</div><div class="hint">${t("evidence")}: <span class="en">${esc(s.evidence)}</span></div></div>`).join("")}</div>
+      <div><h2>${t("weaknesses")}</h2>${(ev.weaknesses || []).map(w => `<div class="box bad" style="margin-bottom:8px" dir="${dir}"><b>${esc(w.area)}</b><div>${esc(w.feedback)}</div></div>`).join("")}</div></div>`;
+  }
+  if ((ev.recommendations || []).length)
+    h += `<div class="card"><h2>${t("recs")}</h2><ul class="list" dir="${dir}">${ev.recommendations.map(r => `<li><b>${esc(r.recommendation)}</b>: ${esc(r.how_to)}</li>`).join("")}</ul></div>`;
+
+  h += `<div class="card"><h2>${t("transcript")}</h2><div class="player"><audio id="player" controls preload="metadata" src="${esc(audioUrl || "")}"></audio>
+      <div class="hint">${t("tx_hint")}</div></div>
+      <div class="tx" id="tx">${(a.transcript || []).map((u, i) => `<div class="line" data-i="${i}" data-start="${u.start}" data-end="${u.end}">
+        <span class="t">${fmtTime(u.start)}</span><span class="r ${u.role}">${t(u.role)}</span><span class="en">${esc(u.text)}</span></div>`).join("")}</div></div>`;
+  h += `<div class="btns"><button class="btn ghost" onclick="window.scrollTo({top:0,behavior:'smooth'})">${t("again")}</button></div>`;
+  $("results").innerHTML = h;
+  $("results").classList.remove("hidden");
+  wirePlayer();
+}
+function wirePlayer() {
+  const p = $("player"); if (!p) return;
+  const lines = [...document.querySelectorAll("#tx .line")];
+  const seek = ms => { p.currentTime = ms / 1000; p.play().catch(() => {}); };
+  lines.forEach(l => l.onclick = () => seek(+l.dataset.start));
+  document.querySelectorAll("[data-seek]").forEach(a => a.onclick = e => { e.preventDefault(); seek(+a.dataset.seek); p.scrollIntoView({ behavior: "smooth", block: "center" }); });
+  let cur = -1;
+  p.ontimeupdate = () => {
+    const ms = p.currentTime * 1000;
+    const i = lines.findIndex(l => ms >= +l.dataset.start && ms <= +l.dataset.end + 400);
+    if (i !== cur) {
+      if (cur >= 0) lines[cur].classList.remove("now");
+      cur = i;
+      if (i >= 0) { lines[i].classList.add("now"); const box = $("tx"); box.scrollTop = lines[i].offsetTop - box.offsetTop - 60; }
+    }
+  };
+}
+
+/* ---------------- Practice ---------------- */
+let bank = {}, queue = [], question = "", roleName = "", lastPractice = null, session = [];
+let recorder = null, chunks = [], recBlob = null, recState = "idle", tick = null, startedAt = 0;
+
+async function loadBank() {
+  try { bank = await (await fetch("practice/questions")).json(); } catch (e) { bank = { General: ["Tell me about yourself."] }; }
+  $("cat").innerHTML = Object.keys(bank).map(k => `<option>${esc(k)}</option>`).join("");
+  $("cat").onchange = () => { roleName = ""; setQueue(bank[$("cat").value]); };
+  setQueue(bank[$("cat").value]);
+}
+function setQueue(list) { queue = [...list].sort(() => Math.random() - .5); nextQuestion(); }
+function nextQuestion() {
+  if (!queue.length) queue = [...(bank[$("cat").value] || [])].sort(() => Math.random() - .5);
+  question = queue.shift() || "Tell me about yourself.";
+  $("qtext").textContent = question;
+  resetRecording();
+  $("presult").classList.add("hidden"); lastPractice = null;
+}
+$("nextq").onclick = nextQuestion;
+$("speak").onclick = () => {
+  if (!("speechSynthesis" in window)) return;
+  speechSynthesis.cancel();
+  const u = new SpeechSynthesisUtterance(question); u.lang = "en-US"; u.rate = .95;
+  const v = speechSynthesis.getVoices().find(v => v.lang && v.lang.startsWith("en"));
+  if (v) u.voice = v;
+  speechSynthesis.speak(u);
+};
+$("gen").onclick = async () => {
+  const role = $("role").value.trim(); if (!role) { $("role").focus(); return; }
+  $("gen").disabled = true; $("pstatus").textContent = "…";
+  try {
+    const fd = new FormData(); fd.append("role", role);
+    const r = await fetch("practice/generate", { method: "POST", body: fd }), j = await r.json();
+    if (!r.ok) throw new Error(j.detail);
+    roleName = role; queue = j.questions; nextQuestion(); $("pstatus").textContent = "";
+  } catch (e) { $("pstatus").textContent = t("gen_fail"); }
+  $("gen").disabled = false;
+};
+
+function resetRecording() {
+  if (recorder && recorder.state === "recording") recorder.stop();
+  recBlob = null; recState = "idle"; $("recl").textContent = t("record"); $("timer").textContent = "";
+  $("myans").classList.add("hidden"); $("fb").disabled = true; $("pstatus").textContent = "";
+}
+$("recbtn").onclick = async () => {
+  if (recState === "recording") { recorder.stop(); return; }
+  try {
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    const mime = ["audio/webm;codecs=opus", "audio/webm", "audio/mp4", "audio/ogg"].find(m => window.MediaRecorder && MediaRecorder.isTypeSupported(m)) || "";
+    recorder = new MediaRecorder(stream, mime ? { mimeType: mime } : undefined);
+    chunks = [];
+    recorder.ondataavailable = e => e.data.size && chunks.push(e.data);
+    recorder.onstop = () => {
+      stream.getTracks().forEach(tr => tr.stop()); clearInterval(tick);
+      recBlob = new Blob(chunks, { type: recorder.mimeType || "audio/webm" });
+      $("myans").src = URL.createObjectURL(recBlob); $("myans").classList.remove("hidden");
+      recState = "recorded"; $("recl").textContent = t("rerecord"); $("fb").disabled = false;
+    };
+    recorder.start(); recState = "recording"; startedAt = Date.now();
+    $("recl").textContent = t("stop"); $("fb").disabled = true; $("myans").classList.add("hidden");
+    tick = setInterval(() => {
+      const s = Math.floor((Date.now() - startedAt) / 1000);
+      $("timer").textContent = fmtTime(s * 1000);
+      if (s >= 180) recorder.stop();
+    }, 250);
+  } catch (e) { $("pstatus").textContent = t("mic_err"); }
+};
+$("fb").onclick = async () => {
+  if (!recBlob) return;
+  $("fb").disabled = true; $("pstatus").textContent = t("p_eval");
+  const ext = (recBlob.type.includes("mp4") ? "m4a" : recBlob.type.includes("ogg") ? "ogg" : "webm");
+  const fd = new FormData();
+  fd.append("file", recBlob, "answer." + ext); fd.append("question", question); fd.append("lang", lang); fd.append("role", roleName);
+  try {
+    const r = await fetch("practice", { method: "POST", body: fd }), j = await r.json();
+    if (!r.ok) throw new Error(j.detail);
+    lastPractice = j; renderPractice(j); $("pstatus").textContent = "";
+    session.push({ q: question, s: j.feedback.score }); renderSession();
+    $("presult").scrollIntoView({ behavior: "smooth" });
+  } catch (e) { $("pstatus").innerHTML = `<span class="err">${esc(e.message)}</span>`; }
+  $("fb").disabled = false;
+};
+function renderPractice(j) {
+  const f = j.feedback || {}, v = j.voice || {}, it = v.interpretation || {}, dir = j.lang === "ar" ? "rtl" : "ltr";
+  $("presult").innerHTML = `<div class="card">
+    <div class="score-wrap">${f.score != null ? ring(f.score * 10) : ""}
+      <div style="flex:1 1 240px"><div class="hint">${t("p_score")}${f.score != null ? `: ${f.score}/10` : ""}</div>
+      <div class="verdict" dir="${dir}">${esc(f.summary || "")}</div>
+      <div class="chips">${f.relevance ? `<span class="chip">${t("relevance")[f.relevance] || f.relevance}</span>` : ""}
+        ${v.speaking_rate != null ? `<span class="chip">${t("rate")}: ${v.speaking_rate} ${t("wps")}</span>` : ""}
+        ${v.filler_ratio != null ? `<span class="chip">${t("fillers")}: ${(v.filler_ratio * 100).toFixed(1)}%</span>` : ""}
+        ${it.confidence_level ? `<span class="chip">${t("confidence")}: ${t(it.confidence_level)}</span>` : ""}</div></div></div>
+    <div class="two" style="margin-top:14px">
+      <div class="box good"><h4>${t("went_well")}</h4><ul class="list" dir="${dir}">${(f.strengths || []).map(x => `<li>${esc(x)}</li>`).join("")}</ul></div>
+      <div class="box bad"><h4>${t("improve")}</h4><ul class="list" dir="${dir}">${(f.improvements || []).map(x => `<li>${esc(x)}</li>`).join("")}</ul></div>
+    </div>
+    ${f.delivery_tip ? `<div class="box plain" style="margin-top:12px" dir="${dir}">💡 <b>${t("tip")}:</b> ${esc(f.delivery_tip)}</div>` : ""}
+    ${f.improved_answer ? `<h3>${t("better")}</h3><div class="box plain en">${esc(f.improved_answer)}</div>` : ""}
+    <h3>${t("you_said")}</h3><div class="box plain en">${esc(j.transcript)}</div></div>`;
+  $("presult").classList.remove("hidden");
+}
+function renderSession() {
+  $("session-card").classList.remove("hidden");
+  $("session").innerHTML = session.map(x => `<li><span class="en">${esc(x.q)}</span>${scoreBadge(x.s)}</li>`).join("");
+}
+
+applyLang();
+loadBank();
+if ("speechSynthesis" in window) speechSynthesis.getVoices();
+</script>
+</body>
+</html>