Initial clean release: production code only

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,19 @@
+# Secrets
+.env
+*.env
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Data outputs
+data/
+*.json
+
+# OS / IDE
+.DS_Store
+.vscode/
+.ipynb_checkpoints/
+app-history/

README.md

@@ -0,0 +1,15 @@
+---
+title: Ai Resume Ranking (hybrid)
+emoji: 🚀
+colorFrom: pink
+colorTo: purple
+sdk: gradio
+sdk_version: 5.50.0
+python_version: "3.11"
+app_file: app.py
+pinned: false
+short_description: iti123-project AI-Powered JD-based Resume Ranking System
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# was sdk_version: 6.2.0

app.py

@@ -0,0 +1,1034 @@
+# app.py
+# with Step1 patch, add try/except wrapper
+# with added step6 agentic explain & interview kit
+# _with_diagnostics_fixed
+
+import os, json, shutil
+from pathlib import Path
+
+import gradio as gr
+import pandas as pd
+
+from dotenv import load_dotenv
+load_dotenv()
+
+from utils.file_loader import load_text_from_file
+from core.jd_processor import generate_jd_rubric
+from core.resume_parser import parse_resume
+from core.matcher import match_candidate_to_jd
+from core.ranking import build_ranking
+from core.explainability import explain_candidate
+
+from openai import OpenAI
+
+import re
+import datetime
+import zipfile
+
+
+# ---------- Folders ----------
+RESUME_DIR = Path("data/resumes")
+CAND_DIR   = Path("data/candidates")
+MATCH_DIR  = Path("data/matches")
+DATA_DIR   = Path("data")
+
+for p in [RESUME_DIR, CAND_DIR, MATCH_DIR]:
+    p.mkdir(parents=True, exist_ok=True)
+
+JD_PATH = DATA_DIR / "jd.json"
+
+
+# ---------- Theme CSS ----------
+def theme_css(mode: str) -> str:
+    # Projector-friendly + layout improvements
+    base = """
+    .gradio-container {
+        max-width: 1200px !important;
+        margin: 0 auto !important;
+        padding-bottom: 24px !important;
+    }
+
+    /* Bigger default text + spacing (projector-friendly) */
+    .gradio-container, .gradio-container * {
+        font-size: 16px;
+        line-height: 1.55;
+    }
+
+    /* Buttons + inputs spacing */
+    button, .gr-button, .gr-input, .gr-textbox, .gr-file, .gr-dropdown {
+        padding-top: 10px !important;
+        padding-bottom: 10px !important;
+    }
+
+    /* Code/JSON blocks */
+    pre, code, .cm-editor, .cm-scroller {
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace !important;
+        font-size: 15px !important;
+        line-height: 1.65 !important;
+        border-radius: 10px !important;
+    }
+
+    /* Make Code component taller by default */
+    .cm-scroller { min-height: 420px !important; }
+    """
+
+    # Light theme
+    light = """
+    :root {
+        --panel-border: #e5e7eb;
+        --code-bg: #f8fafc;
+        --code-fg: #0f172a;
+    }
+    body { background: #f5f5f5; }
+    pre, code, .cm-editor {
+        background-color: var(--code-bg) !important;
+        color: var(--code-fg) !important;
+        border: 1px solid var(--panel-border) !important;
+    }
+    """
+
+    # HF-like dark theme (matches HF dark vibe better)
+    hf_dark = """
+    :root {
+    --panel-border: #1f2937;
+    --code-bg: #0f172a;
+    --code-fg: #e5e7eb;
+
+    /* Text colors */
+    --title-fg: #ffffff;        /* pure white */
+    --header-fg: #d1d5db;       /* light grey */
+    --muted-fg: #9ca3af;        /* passive text */
+}
+
+body { background: #0b1220; }
+
+/* ===== Main page title ===== */
+h1, h1 * {
+    color: var(--title-fg) !important;
+    font-weight: 700 !important;
+}
+
+/* ===== Section headers ===== */
+h2, h3, h4,
+h2 *, h3 *, h4 * {
+    color: var(--header-fg) !important;
+    font-weight: 600 !important;
+}
+
+/* ===== Tab labels (inactive) ===== */
+button[role="tab"] {
+    color: var(--muted-fg) !important;
+    font-weight: 500 !important;
+}
+
+/* ===== Active tab ===== */
+button[role="tab"][aria-selected="true"] {
+    color: #fb923c !important;   /* your orange highlight */
+    font-weight: 700 !important;
+}
+
+/* ===== Code / JSON blocks ===== */
+pre, code, .cm-editor {
+    background-color: var(--code-bg) !important;
+    color: var(--code-fg) !important;
+    border: 1px solid var(--panel-border) !important;
+}
+    """
+
+    # High contrast theme
+    high_contrast = """
+:root {
+    --panel-border: #ffffff;
+    --code-bg: #000000;
+    --code-fg: #ffffff;
+
+    /* seeable text colors */
+    --title-fg: #ffffff;
+    --header-fg: #ffffff;
+    --muted-fg: #e5e7eb;   /* brighter grey for inactive tabs */
+}
+
+body { background: #000000; }
+
+/* ===== Main page title ===== */
+h1, h1 * {
+    color: var(--title-fg) !important;
+    font-weight: 800 !important;
+}
+
+/* ===== Section headers ===== */
+h2, h3, h4,
+h2 *, h3 *, h4 * {
+    color: var(--header-fg) !important;
+    font-weight: 700 !important;
+}
+
+/* ===== Tab labels (inactive) ===== */
+button[role="tab"] {
+    color: var(--muted-fg) !important;
+    font-weight: 600 !important;
+}
+
+/* ===== Active tab ===== */
+button[role="tab"][aria-selected="true"] {
+    color: #ffd500 !important;   /* high contrast yellow */
+    font-weight: 800 !important;
+}
+
+/* ===== Code / JSON blocks ===== */
+pre, code, .cm-editor {
+    background-color: var(--code-bg) !important;
+    color: var(--code-fg) !important;
+    border: 2px solid var(--panel-border) !important;
+}
+"""
+
+    css_map = {
+        "Light": light,
+        "HF Dark": hf_dark,
+        "High Contrast": high_contrast,
+    }
+    return base + css_map.get(mode, hf_dark)
+
+
+def _ensure_api_key():
+    if not os.getenv("OPENAI_API_KEY"):
+        raise RuntimeError(
+            "OPENAI_API_KEY is not set. "
+            "On Hugging Face: Settings → Secrets → OPENAI_API_KEY. "
+            "On local/Colab: set environment variable before running."
+        )
+
+
+def _pretty_json(obj) -> str:
+    return json.dumps(obj, indent=2, ensure_ascii=False)
+
+
+# ---------- Steps ----------
+
+def step1_generate_jd(file_obj):
+    try:
+        _ensure_api_key()
+        if file_obj is None:
+            return "", "Please upload a JD file."
+
+        with open(file_obj.name, "rb") as f:
+            jd_text = load_text_from_file(f)
+
+        jd_rubric = generate_jd_rubric(jd_text)
+
+        JD_PATH.parent.mkdir(parents=True, exist_ok=True)
+        with open(JD_PATH, "w", encoding="utf-8") as out:
+            json.dump(jd_rubric, out, indent=2, ensure_ascii=False)
+
+        return _pretty_json(jd_rubric), f"✅ JD rubric saved to {JD_PATH}"
+
+    except Exception as e:
+        return "", f"❌ Step 1 failed: {type(e).__name__}: {e}"
+
+
+def step2_save_resumes(files, overwrite):
+    if not files:
+        return "Please upload at least one resume."
+
+    saved, skipped = 0, 0
+    for f in files:
+        dest = RESUME_DIR / Path(f.name).name
+        if dest.exists() and not overwrite:
+            skipped += 1
+            continue
+        shutil.copyfile(f.name, dest)
+        saved += 1
+
+    msg = f"✅ Saved {saved} resume(s) into {RESUME_DIR}"
+    if skipped:
+        msg += f" | ⏭ Skipped {skipped} duplicate(s) (overwrite=False)"
+    return msg
+
+
+
+def step3_parse_resumes():
+    try:
+        _ensure_api_key()
+        resume_files = sorted([p for p in RESUME_DIR.iterdir() if p.suffix.lower() in [".pdf", ".docx"]])
+
+        if not resume_files:
+            return "No resumes found in data/resumes. Upload resumes first."
+
+        CAND_DIR.mkdir(parents=True, exist_ok=True)
+
+        failed = 0
+        for path in resume_files:
+            try:
+                with open(path, "rb") as f:
+                    resume_text = load_text_from_file(f)
+
+                candidate_data = parse_resume(resume_text, path.name)
+
+                out_path = CAND_DIR / (path.stem + ".json")
+                with open(out_path, "w", encoding="utf-8") as out:
+                    json.dump(candidate_data, out, indent=2, ensure_ascii=False)
+
+            except Exception as e:
+                failed += 1
+                DATA_DIR.mkdir(parents=True, exist_ok=True)
+                with open(DATA_DIR / "parse_step3_errors.log", "a", encoding="utf-8") as log:
+                    log.write(f"{path.name}: {type(e).__name__}: {e}\n")
+
+        msg = f"✅ Parsed {len(resume_files) - failed} resume(s) into {CAND_DIR}"
+        if failed:
+            msg += f" | ⚠️ Failed: {failed} (see data/parse_step3_errors.log)"
+        return msg
+
+    except Exception as e:
+        return f"❌ Step 3 failed: {type(e).__name__}: {e}"
+
+
+
+def step4_generate_matches():
+    try:
+        _ensure_api_key()
+        if not JD_PATH.exists():
+            return "No JD rubric found. Run Step 1 first."
+
+        cand_files = sorted([p for p in CAND_DIR.iterdir() if p.suffix.lower() == ".json"])
+        if not cand_files:
+            return "No candidates found. Run Step 3 first."
+
+        with open(JD_PATH, "r", encoding="utf-8") as f:
+            jd_rubric = json.load(f)
+
+        created, failed = 0, 0
+        for cf in cand_files:
+            try:
+                with open(cf, "r", encoding="utf-8") as f:
+                    candidate = json.load(f)
+
+                match_result = match_candidate_to_jd(jd_rubric, candidate)
+
+                out_path = MATCH_DIR / (cf.stem + "_match.json")
+                with open(out_path, "w", encoding="utf-8") as out:
+                    json.dump(match_result, out, indent=2, ensure_ascii=False)
+
+                created += 1
+            except Exception as e:
+                failed += 1
+                DATA_DIR.mkdir(parents=True, exist_ok=True)
+                with open(DATA_DIR / "match_errors.log", "a", encoding="utf-8") as log:
+                    log.write(f"{cf.name}: {type(e).__name__}: {e}\n")
+
+        msg = f"✅ Created {created} match file(s) in {MATCH_DIR}"
+        if failed:
+            msg += f" | ⚠️ Failed: {failed} (see data/match_errors.log)"
+        return msg
+
+    except Exception as e:
+        return f"❌ Step 4 failed: {type(e).__name__}: {e}"
+
+
+def step4_view_match(selected):
+    if not selected:
+        return ""
+    path = MATCH_DIR / selected
+    if not path.exists():
+        return ""
+    with open(path, "r", encoding="utf-8") as f:
+        return _pretty_json(json.load(f))
+
+
+
+def step5_rank(top_k):
+    try:
+        _ensure_api_key()
+        if not JD_PATH.exists():
+            return None, "No JD rubric found. Run Step 1 first."
+
+        if not any(p.name.endswith("_match.json") for p in MATCH_DIR.iterdir()):
+            return None, "No match files found. Run Step 4 first."
+
+        ranking = build_ranking(top_k=int(top_k))
+
+        rows = []
+        for i, r in enumerate(ranking.get("ranking", []), start=1):
+            b = r.get("breakdown", {}) or {}
+            rows.append({
+                "Rank": i,
+                "Candidate": r.get("candidate_name", ""),
+                "Score": r.get("total_score", 0),
+                "Base Score": b.get("base_score", 0),
+                "Adj": b.get("bonus_penalty_adjustment", 0),
+                "Pos": b.get("positive_count", 0),
+                "Neg": b.get("negative_count", 0),
+                "Must-have": b.get("must_have_coverage", 0),
+                "Nice-to-have": b.get("nice_to_have_coverage", 0),
+                "Experience": b.get("experience_score", 0),
+                "Match File": r.get("match_file", "")
+            })
+
+        df = pd.DataFrame(rows)
+        return df, "✅ Ranking generated (also saved to data/ranking.json)"
+
+    except Exception as e:
+        return None, f"❌ Step 5 failed: {type(e).__name__}: {e}"
+
+
+def list_match_files():
+    return sorted([p.name for p in MATCH_DIR.iterdir() if p.name.endswith("_match.json")])
+
+def step6_explain(match_filename):
+    try:
+        _ensure_api_key()
+        if not match_filename:
+            return "", "Please select a match file."
+
+        match_path = MATCH_DIR / match_filename
+        if not match_path.exists():
+            return "", "Match file not found. Run Step 4 first."
+
+        if not JD_PATH.exists():
+            return "", "JD rubric not found. Run Step 1 first."
+
+        explanation = explain_candidate(
+            jd_path=str(JD_PATH),
+            match_path=str(match_path),
+            rank=None
+        )
+
+        return json.dumps(explanation, indent=2, ensure_ascii=False), "✅ Explanation generated"
+
+    except Exception as e:
+        return "", f"❌ Step 6 failed: {type(e).__name__}: {e}"
+
+def _tail_file(path: Path, max_lines: int = 200) -> str:
+    """Read the last N lines of a text file safely."""
+    if not path.exists():
+        return f"(No file found) {path}"
+
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            lines = f.readlines()
+        if len(lines) <= max_lines:
+            return "".join(lines)
+        return "".join(lines[-max_lines:])
+    except Exception as e:
+        return f"Failed to read {path}: {type(e).__name__}: {e}"
+
+
+def view_diagnostics_log(show: bool, which: str, last_n: int) -> str:
+    if not show:
+        return "Diagnostics hidden. Enable 'Show diagnostics' to view logs."
+
+    log_map = {
+        "Resume parser (data/parse_errors.log)": DATA_DIR / "parse_errors.log",
+        "Step 3 batch parse (data/parse_step3_errors.log)": DATA_DIR / "parse_step3_errors.log",
+        "Step 4 matching (data/match_errors.log)": DATA_DIR / "match_errors.log",
+    }
+    path = log_map.get(which)
+    if not path:
+        return "Unknown log selection."
+
+    n = int(last_n) if last_n else 200
+    n = max(20, min(n, 2000))  # clamp for safety
+    return _tail_file(path, max_lines=n)
+
+
+def clear_diagnostics_log(show: bool, which: str) -> str:
+    if not show:
+        return "Diagnostics hidden. Enable 'Show diagnostics' to clear logs."
+
+    log_map = {
+        "Resume parser (data/parse_errors.log)": DATA_DIR / "parse_errors.log",
+        "Step 3 batch parse (data/parse_step3_errors.log)": DATA_DIR / "parse_step3_errors.log",
+        "Step 4 matching (data/match_errors.log)": DATA_DIR / "match_errors.log",
+    }
+    path = log_map.get(which)
+    if not path:
+        return "Unknown log selection."
+
+    try:
+        DATA_DIR.mkdir(parents=True, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            f.write("")
+        return f"✅ Cleared {path}"
+    except Exception as e:
+        return f"Failed to clear {path}: {type(e).__name__}: {e}"
+
+# ---------- Weight Review & Adjustment (Step 1 enhancement) ----------
+
+def _get_weight_dict(jd_rubric: dict):
+    """
+    Returns (weight_dict, mode) where mode indicates which key was used.
+    Preference order:
+      1) recommended_weights  (expected to be percentage numbers that sum to 100)
+      2) weights             (optional legacy key)
+    """
+    if not isinstance(jd_rubric, dict):
+        return None, "none"
+    rw = jd_rubric.get("recommended_weights")
+    if isinstance(rw, dict) and rw:
+        return rw, "recommended_weights"
+    w = jd_rubric.get("weights")
+    if isinstance(w, dict) and w:
+        return w, "weights"
+    return None, "none"
+
+
+def step1_prepare_weight_editor(jd_json_text: str):
+    """
+    Build an editable table:
+      label | recommended | adjusted | key
+    """
+    try:
+        jd_rubric = json.loads(jd_json_text) if jd_json_text else {}
+    except Exception:
+        return pd.DataFrame([]), "none", "⚠️ Could not parse JD JSON. Generate JD rubric first."
+
+    weight_dict, mode = _get_weight_dict(jd_rubric)
+    if mode == "none" or not weight_dict:
+        return pd.DataFrame([]), "none", "ℹ️ No editable weights detected. Expected 'recommended_weights' in JD JSON."
+
+    rows = []
+    for k, v in weight_dict.items():
+        try:
+            vv = float(v)
+        except Exception:
+            vv = v
+        rows.append({
+            "label": k.replace("_", " ").title(),
+            "recommended": vv,
+            "adjusted": vv,
+            "key": k
+        })
+
+    df = pd.DataFrame(rows)[["label", "recommended", "adjusted", "key"]]
+
+    total = 0.0
+    try:
+        total = float(df["adjusted"].sum())
+    except Exception:
+        total = 0.0
+
+    hint = ""
+    if mode == "recommended_weights":
+        hint = f" Current total = {total:.2f} (must be 100)."
+    return df, mode, f"✅ Loaded {len(rows)} weight item(s). Edit 'adjusted' then click Apply.{hint}"
+
+
+def step1_apply_weight_adjustments(jd_json_text: str, weight_df, mode: str):
+    """
+    Apply edited weights back into JD JSON and save to data/jd.json.
+    Closed-loop validation:
+      - If mode == recommended_weights, adjusted weights must sum to 100.
+    """
+    try:
+        jd_rubric = json.loads(jd_json_text) if jd_json_text else {}
+    except Exception as e:
+        return "", f"❌ Cannot apply weights: JD JSON invalid: {type(e).__name__}: {e}"
+
+    if mode not in ("recommended_weights", "weights"):
+        return _pretty_json(jd_rubric), "ℹ️ No weight adjustments applied (no editable weights detected)."
+
+    try:
+        df = weight_df if isinstance(weight_df, pd.DataFrame) else pd.DataFrame(weight_df)
+    except Exception as e:
+        return _pretty_json(jd_rubric), f"❌ Cannot read edited weights table: {type(e).__name__}: {e}"
+
+    if not {"key", "adjusted"}.issubset(set(df.columns)):
+        return _pretty_json(jd_rubric), "❌ Weights table format unexpected. Click 'Load weights' again."
+
+    adjusted = {}
+    try:
+        for _, r in df.iterrows():
+            k = str(r.get("key"))
+            adjusted[k] = float(r.get("adjusted"))
+    except Exception as e:
+        return _pretty_json(jd_rubric), f"❌ Adjusted weights must be numeric: {type(e).__name__}: {e}"
+
+    total = sum(adjusted.values())
+    if mode == "recommended_weights" and abs(total - 100.0) > 1e-6:
+        return _pretty_json(jd_rubric), f"⚠️ Adjusted weights must add up to 100. Current total = {total:.2f}. No changes applied."
+
+    if mode == "recommended_weights":
+        if "recommended_weights_original" not in jd_rubric and isinstance(jd_rubric.get("recommended_weights"), dict):
+            jd_rubric["recommended_weights_original"] = jd_rubric["recommended_weights"]
+        jd_rubric["recommended_weights"] = adjusted
+    else:
+        jd_rubric["weights"] = adjusted
+
+    try:
+        JD_PATH.parent.mkdir(parents=True, exist_ok=True)
+        with open(JD_PATH, "w", encoding="utf-8") as out:
+            json.dump(jd_rubric, out, indent=2, ensure_ascii=False)
+    except Exception as e:
+        return _pretty_json(jd_rubric), f"⚠️ Weights updated but failed to save: {type(e).__name__}: {e}"
+
+    return _pretty_json(jd_rubric), "✅ Weight adjustments applied and saved to data/jd.json"
+
+# ---------- Email Generator (Step 7) ----------
+
+def _llm_polish_email(draft_email: str,
+                      candidate_name: str,
+                      role_title: str,
+                      company_name: str,
+                      strengths,
+                      gaps,
+                      next_step: str,
+                      tone: str,
+                      model: str,
+                      temperature: float):
+    """
+    Returns: (email_text, used_ai: bool, err: str)
+    Uses OpenAI Responses API (SDK v2 compatible).
+    """
+    api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        return draft_email, False, "OPENAI_API_KEY missing"
+
+    try:
+        client = OpenAI(api_key=api_key)
+
+        strengths_list = strengths or []
+        gaps_list = gaps or []
+
+        strengths_txt = "\n".join([f"- {s}" for s in strengths_list[:5]]) or "- (To be discussed)"
+        gaps_txt = "\n".join([f"- {g}" for g in gaps_list[:5]]) or "- (None noted)"
+
+        style_rules = {
+            "Warm": "Warm, respectful, encouraging.",
+            "Formal": "Formal, concise, professional.",
+            "Casual": "Friendly, short, professional (not slangy).",
+        }
+        style = style_rules.get(tone or "Warm", style_rules["Warm"])
+
+        system_prompt = (
+            "You are an HR assistant. Rewrite the email draft into a polished, professional hiring email.\n"
+            "Hard requirements:\n"
+            "- Output plain text only.\n"
+            "- Keep a Subject line starting with 'Subject:'.\n"
+            "- 150–220 words.\n"
+            "- Do NOT invent facts.\n"
+            "- IMPORTANT: Do not reuse any sentence from the draft longer than 8 words. Rephrase fully.\n"
+        )
+
+        user_prompt = f"""
+Tone: {style}
+
+Role title: {role_title}
+Company: {company_name}
+Candidate: {candidate_name}
+
+Key strengths (use if relevant):
+{strengths_txt}
+
+Potential gaps / points to clarify (use gently):
+{gaps_txt}
+
+Next step text (must include):
+{next_step}
+
+Draft to rewrite (rewrite fully, don’t copy sentences):
+{draft_email}
+""".strip()
+
+        resp = client.responses.create(
+            model=(model or "gpt-4o-mini"),
+            input=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            temperature=float(temperature) if temperature is not None else 0.6,
+            max_output_tokens=450,
+        )
+
+        out = (resp.output_text or "").strip()
+        if not out:
+            return draft_email, False, "Empty response from model"
+
+        if out.strip() == draft_email.strip():
+            return draft_email, True, "Model returned identical text"
+
+        return out, True, ""
+
+    except Exception as e:
+        return draft_email, False, f"{type(e).__name__}: {e}"
+
+
+
+RANKING_PATH = DATA_DIR / "ranking.json"
+
+def _safe_filename(s: str) -> str:
+    s = re.sub(r"[^\w\-\. ]+", "", s.strip())
+    s = re.sub(r"\s+", "_", s)
+    return s[:80] or "candidate"
+
+
+def _load_json(path: Path) -> dict:
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def load_ranking_for_email():
+    """
+    Returns a list of rows for email generation: [{rank, candidate_name, match_file, score}, ...]
+    """
+    if not RANKING_PATH.exists():
+        return [], "No ranking.json found. Run Step 5 first."
+
+    try:
+        data = _load_json(RANKING_PATH)
+        items = data.get("ranking", []) if isinstance(data, dict) else []
+        rows = []
+        for r in items:
+            rows.append({
+                "rank": r.get("rank") or r.get("Rank") or "",
+                "candidate_name": r.get("candidate_name") or r.get("Candidate") or "",
+                "score": r.get("total_score") or r.get("Score") or 0,
+                "match_file": r.get("match_file") or r.get("Match File") or ""
+            })
+        # If rank not present, enumerate
+        for i, rr in enumerate(rows, start=1):
+            if not rr.get("rank"):
+                rr["rank"] = i
+        return rows, f"✅ Loaded {len(rows)} candidate(s) from data/ranking.json"
+    except Exception as e:
+        return [], f"❌ Failed to read ranking.json: {type(e).__name__}: {e}"
+
+
+def _extract_candidate_highlights(match_data: dict):
+    """
+    Best-effort extraction of strengths/gaps from match JSON.
+    Returns (strengths_list, gaps_list, summary_text)
+    """
+    if not isinstance(match_data, dict):
+        return [], [], ""
+
+    strengths = match_data.get("strengths") or match_data.get("positives") or match_data.get("highlights") or []
+    gaps = match_data.get("gaps") or match_data.get("negatives") or match_data.get("risks") or []
+
+    # If stored as strings, wrap
+    if isinstance(strengths, str):
+        strengths = [strengths]
+    if isinstance(gaps, str):
+        gaps = [gaps]
+
+    # fallback: sometimes stored under "analysis" or "summary"
+    summary = match_data.get("summary") or match_data.get("jd_aligned_summary") or match_data.get("final_summary") or ""
+    if isinstance(summary, dict):
+        summary = json.dumps(summary, ensure_ascii=False)
+
+    # ensure lists
+    strengths = [str(x) for x in strengths if x]
+    gaps = [str(x) for x in gaps if x]
+    return strengths[:5], gaps[:5], str(summary)[:1200]
+
+
+def _template_email(candidate_name: str, role_title: str, company_name: str, sender_name: str,
+                    strengths, next_step: str, contact: str, tone: str):
+    """
+    Deterministic, fast email template (no LLM) suitable for HF stability.
+    """
+    greet_name = candidate_name.strip() or "there"
+
+    if tone == "Warm":
+        opening = f"Thank you for taking the time to apply for the {role_title} position at {company_name}."
+    elif tone == "Formal":
+        opening = f"Thank you for your application for the {role_title} position at {company_name}."
+    else:
+        opening = f"Thanks for applying for the {role_title} role at {company_name}."
+
+    bullets = ""
+    if strengths:
+        bullets = "\n".join([f"- {s}" for s in strengths])
+
+    body = f"""Subject: Next steps — {role_title} at {company_name}
+
+Hi {greet_name},
+
+{opening}
+
+After reviewing your application, we’d like to move you forward to the next stage.
+
+Key highlights from your profile:
+{bullets if bullets else "- (Highlights will be discussed during the interview)"}
+
+Next step:
+{next_step}
+
+If you have any questions, reply to this email or contact us at {contact}.
+
+Best regards,
+{sender_name}
+{company_name}
+"""
+    return body
+
+
+def step7_generate_emails(top_k: int,
+                         role_title: str,
+                         company_name: str,
+                         sender_name: str,
+                         contact_email: str,
+                         next_step_text: str,
+                         tone: str,
+                         use_ai: bool,
+                         ai_model: str,
+                         ai_temperature: float):
+    """
+    V2.1 — Email generator with optional AI polish (OpenAI Responses API).
+    Always falls back to template output on error.
+    """
+    try:
+        rows, msg = load_ranking_for_email()
+        if not rows:
+            return None, "", msg
+
+        k = int(top_k) if top_k else 5
+        k = max(1, min(k, len(rows)))
+        rows = rows[:k]
+
+        out_dir = DATA_DIR / "out_emails"
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        stamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+        zip_path = out_dir / f"emails_top{k}_{stamp}.zip"
+
+        previews = []
+        ai_used = False
+        last_ai_reason = ''
+
+        with zipfile.ZipFile(zip_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+            for r in rows:
+                match_file = r.get("match_file", "")
+                match_path = MATCH_DIR / match_file if match_file else None
+
+                strengths, gaps, summary = [], [], ""
+                if match_path and match_path.exists():
+                    try:
+                        mdata = _load_json(match_path)
+                        strengths, gaps, summary = _extract_candidate_highlights(mdata)
+                    except Exception:
+                        pass
+
+                email_text = _template_email(
+                    candidate_name=r.get("candidate_name", ""),
+                    role_title=role_title or "the role",
+                    company_name=company_name or "our company",
+                    sender_name=sender_name or "Hiring Team",
+                    strengths=strengths,
+                    next_step=next_step_text or "Please reply with your availability for a short interview this week.",
+                    contact=contact_email or "hr@example.com",
+                    tone=tone or "Warm"
+                )
+
+                # Optional AI polish (V2)
+                if use_ai:
+                    polished, used_ai, reason = _llm_polish_email(
+                        draft_email=email_text,
+                        candidate_name=r.get("candidate_name", "") or "",
+                        role_title=role_title or "the role",
+                        company_name=company_name or "our company",
+                        strengths=strengths,
+                        gaps=gaps,
+                        next_step=next_step_text or "Please reply with your availability for a short interview this week.",
+                        tone=tone or "Warm",
+                        model=ai_model or "gpt-4o-mini",
+                        temperature=ai_temperature if ai_temperature is not None else 0.6,
+                    )
+
+                    # Track why AI didn't change content (for clarity)
+                    last_ai_reason = reason or last_ai_reason
+
+                    if used_ai and polished and polished.strip() != email_text.strip():
+                        ai_used = True
+                        email_text = polished
+
+                filename = f"Rank{r.get('rank')}_{_safe_filename(r.get('candidate_name','candidate'))}.txt"
+                zf.writestr(filename, email_text)
+
+                if len(previews) < 2:
+                    previews.append(email_text)
+
+        preview_text = ""
+        if previews:
+            preview_text = "\n\n" + ("-" * 40) + "\n\n".join(previews)
+
+        status = f"✅ Generated {k} email draft(s)."
+        if use_ai:
+            if ai_used:
+                status += f" ✨ AI polish applied (model={ai_model or 'gpt-4o-mini'})."
+            else:
+                reason = last_ai_reason or "AI not applied (fallback to template)."
+                status += f" ⚠️ AI polish not applied. Reason: {reason}"
+
+        return str(zip_path), preview_text, status
+
+    except Exception as e:
+        return None, "", f"❌ Step 7 failed: {type(e).__name__}: {e}"
+
+
+# ---------- UI ----------
+with gr.Blocks(title="AI-Powered Resume Screening & Ranking System") as demo:
+    gr.Markdown("# 📄 AI-Powered JD-Based Resumes Ranking System")
+
+    # Theme selector + CSS injector
+    with gr.Row():
+        theme_mode = gr.Dropdown(
+            choices=["Light", "HF Dark", "High Contrast"],
+            value="HF Dark",
+            label="Reader Theme"
+        )
+
+    style_tag = gr.HTML(value=f"<style>{theme_css('HF Dark')}</style>")
+
+    def apply_theme(mode):
+        return gr.HTML(value=f"<style>{theme_css(mode)}</style>")
+
+    theme_mode.change(fn=apply_theme, inputs=theme_mode, outputs=style_tag)
+
+    with gr.Tab("Step 1 — JD Upload & Rubric"):
+        jd_file = gr.File(label="Upload JD (PDF/DOCX/TXT)")
+        jd_btn = gr.Button("Generate JD Rubric")
+
+        # Use Code for better readability + styling control
+        jd_json = gr.Code(label="JD Rubric (JSON)", language="json")
+        jd_status = gr.Textbox(label="Status")
+
+        jd_btn.click(step1_generate_jd, inputs=[jd_file], outputs=[jd_json, jd_status])
+
+        gr.Markdown("### Review & adjust weightage (optional)")
+        gr.Markdown("Edit the **adjusted** column. For `recommended_weights`, the adjusted values must sum to **100**.")
+
+        load_weights_btn = gr.Button("Load weights from JD JSON")
+        weight_mode = gr.State(value="none")
+        weight_msg = gr.Textbox(label="Weight editor status", interactive=False)
+
+        weight_df = gr.Dataframe(
+            label="Editable weights (edit 'adjusted' column)",
+            headers=["label", "recommended", "adjusted", "key"],
+            datatype=["str", "number", "number", "str"],
+            interactive=True,
+            wrap=True,
+            row_count=(0, "dynamic"),
+            col_count=(4, "fixed"),
+        )
+
+        apply_weights_btn = gr.Button("Apply weight adjustments to JD (save)")
+
+        load_weights_btn.click(
+            step1_prepare_weight_editor,
+            inputs=[jd_json],
+            outputs=[weight_df, weight_mode, weight_msg],
+        )
+
+        apply_weights_btn.click(
+            step1_apply_weight_adjustments,
+            inputs=[jd_json, weight_df, weight_mode],
+            outputs=[jd_json, jd_status],
+        )
+
+
+    with gr.Tab("Step 2 — Resume Batch Upload"):
+        resume_files = gr.File(label="Upload resumes (PDF/DOCX)", file_count="multiple")
+        overwrite = gr.Checkbox(label="Overwrite duplicates", value=False)
+        save_btn = gr.Button("Save Resumes to data/resumes")
+        save_status = gr.Textbox(label="Status")
+        save_btn.click(step2_save_resumes, inputs=[resume_files, overwrite], outputs=[save_status])
+
+    with gr.Tab("Step 3 — Parse Resumes"):
+        parse_btn = gr.Button("Parse Resumes → data/candidates")
+        parse_status = gr.Textbox(label="Status")
+        parse_btn.click(step3_parse_resumes, inputs=[], outputs=[parse_status])
+
+    with gr.Tab("Step 4 — JD-aligned Summaries"):
+        match_btn = gr.Button("Generate match files → data/matches")
+        match_status = gr.Textbox(label="Status")
+
+        refresh_btn = gr.Button("Refresh match list")
+        match_list = gr.Dropdown(choices=[], label="Select a match file")
+        view_btn = gr.Button("View selected match JSON")
+
+        match_json = gr.Code(label="Match JSON", language="json")
+
+        match_btn.click(step4_generate_matches, inputs=[], outputs=[match_status])
+        refresh_btn.click(lambda: gr.update(choices=list_match_files()), inputs=[], outputs=[match_list])
+        view_btn.click(step4_view_match, inputs=[match_list], outputs=[match_json])
+
+    with gr.Tab("Step 5 — Scoring & Ranking"):
+        topk = gr.Number(value=10, label="Top K", precision=0)
+        rank_btn = gr.Button("Generate Ranking")
+        rank_df = gr.Dataframe(label="Top K Ranking")
+        rank_status = gr.Textbox(label="Status")
+
+        rank_btn.click(step5_rank, inputs=[topk], outputs=[rank_df, rank_status])
+
+    with gr.Tab("Step 6 — Explain & Interview Kit (Agentic)"):
+        refresh6 = gr.Button("Refresh match list")
+        match_pick6 = gr.Dropdown(choices=[], label="Select a match file")
+        explain_btn = gr.Button("Generate Explanation (CrewAI)")
+        explain_json = gr.Code(label="Explainability Output (JSON)", language="json")
+        explain_status = gr.Textbox(label="Status")
+
+        refresh6.click(lambda: gr.update(choices=list_match_files()), inputs=[], outputs=[match_pick6])
+        explain_btn.click(step6_explain, inputs=[match_pick6], outputs=[explain_json, explain_status])
+
+
+    with gr.Tab("Step 7 — Email Generator"):
+        gr.Markdown("### Generate professional email drafts for Top‑K candidates")
+        gr.Markdown("This step uses a fast **template-based** generator (HF-stable). We can add AI polishing later if you want.")
+
+        with gr.Row():
+            topk_email = gr.Number(value=5, precision=0, label="Top-K candidates")
+            tone = gr.Dropdown(choices=["Warm", "Formal", "Casual"], value="Warm", label="Tone")
+
+        with gr.Accordion("V2 (Optional) — AI polish emails", open=False):
+            use_ai = gr.Checkbox(label="Use AI to polish emails (requires OPENAI_API_KEY on HF)", value=False)
+            ai_model = gr.Textbox(label="Model", value="gpt-4o-mini")
+            ai_temperature = gr.Slider(minimum=0.0, maximum=1.0, value=0.3, step=0.1, label="Temperature")
+
+        role_title = gr.Textbox(label="Role title", value="(Your role title)")
+        company_name = gr.Textbox(label="Company name", value="(Your company)")
+        sender_name = gr.Textbox(label="Sender name", value="Hiring Team")
+        contact_email = gr.Textbox(label="Contact email", value="hr@yourcompany.com")
+        next_step_text = gr.Textbox(
+            label="Next step message (shown in the email)",
+            value="Please reply with your availability for a 20–30 minute interview this week.",
+            lines=2
+        )
+
+        gen_btn = gr.Button("Generate emails + ZIP download")
+        email_zip = gr.File(label="Download ZIP (Top‑K emails)")
+        email_preview = gr.Textbox(label="Preview (first 1–2 emails)", lines=16, interactive=False)
+        email_status = gr.Textbox(label="Status", interactive=False)
+
+        gen_btn.click(
+            step7_generate_emails,
+            inputs=[topk_email, role_title, company_name, sender_name, contact_email, next_step_text, tone, use_ai, ai_model, ai_temperature],
+            outputs=[email_zip, email_preview, email_status]
+        )
+
+    with gr.Tab("Admin — Diagnostics"):
+        gr.Markdown("### Diagnostics (Admin)\nEnable this only when you need to troubleshoot or validate robustness.")
+        show_diag = gr.Checkbox(label="Show diagnostics", value=False)
+
+        log_choice = gr.Dropdown(
+            choices=[
+                "Resume parser (data/parse_errors.log)",
+                "Step 3 batch parse (data/parse_step3_errors.log)",
+                "Step 4 matching (data/match_errors.log)",
+            ],
+            value="Resume parser (data/parse_errors.log)",
+            label="Select log"
+        )
+
+        last_n = gr.Number(value=200, precision=0, label="Show last N lines (20–2000)")
+        with gr.Row():
+            refresh_log = gr.Button("Refresh log")
+            clear_log = gr.Button("Clear selected log")
+
+        log_view = gr.Textbox(label="Log output", lines=20, interactive=False)
+
+        refresh_log.click(view_diagnostics_log, inputs=[show_diag, log_choice, last_n], outputs=[log_view])
+        clear_log.click(clear_diagnostics_log, inputs=[show_diag, log_choice], outputs=[log_view])
+# HF Spaces: share should be False (share links are mainly for local use)
+
+demo.launch(share=False)

core/__init__.py

@@ -0,0 +1,2 @@
+# utils/__init__.py
+# core/__init__.py

core/crew_explainer.py

@@ -0,0 +1,101 @@
+import os
+import json
+from pathlib import Path
+
+from crewai import Agent, Task, Crew, Process
+
+# ---------- Helpers ----------
+def _ensure_key():
+    if not os.getenv("OPENAI_API_KEY"):
+        raise RuntimeError("OPENAI_API_KEY is not set (HF: Settings → Secrets → OPENAI_API_KEY).")
+
+def _load_json(path: str):
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+def _dump_json(obj) -> str:
+    return json.dumps(obj, ensure_ascii=False, indent=2)
+
+# ---------- Agent ----------
+def _explainer_agent():
+    return Agent(
+        role="Hiring Explainability Analyst",
+        goal="Explain and justify candidate ranking using provided JD rubric and match JSON evidence.",
+        backstory=(
+            "You help HR reviewers understand why a candidate is ranked, what gaps exist, "
+            "and what interview questions to ask. You do not change the original scoring."
+        ),
+        verbose=False,
+        max_iter=1,
+    )
+
+# ---------- Public API (called by app.py) ----------
+def generate_explanation(jd_path: str, match_path: str, top_k_rank: int | None = None) -> dict:
+    """
+    Returns a structured JSON:
+    {
+      "summary": "...",
+      "strengths": [...],
+      "gaps": [...],
+      "risk_flags": [...],
+      "interview_questions": [...],
+      "recommended_next_step": "..."
+    }
+    """
+    _ensure_key()
+
+    jd = _load_json(jd_path)
+    match_obj = _load_json(match_path)
+
+    # Keep prompt compact and safe for latency
+    prompt_payload = {
+        "jd_rubric": jd,
+        "match": match_obj,
+        "ranking_context": {"top_k_rank": top_k_rank},
+        "output_schema": {
+            "summary": "string (2-4 sentences)",
+            "strengths": ["bullet strings"],
+            "gaps": ["bullet strings"],
+            "risk_flags": ["bullet strings"],
+            "interview_questions": ["bullet strings (5-8 questions)"],
+            "recommended_next_step": "string (one action)"
+        }
+    }
+
+    task = Task(
+        description=(
+            "You will produce an explainability report for a candidate.\n"
+            "Use the provided payload which includes the JD rubric and the candidate match JSON.\n"
+            "Rules:\n"
+            "- Do NOT invent skills/experience not present in the match JSON.\n"
+            "- Tie strengths/gaps to rubric categories if possible.\n"
+            "- If evidence is insufficient, say so as a risk_flag.\n"
+            "- Output MUST be valid JSON only, matching the output_schema exactly.\n\n"
+            f"PAYLOAD:\n{_dump_json(prompt_payload)}"
+        ),
+        expected_output="Valid JSON only.",
+        agent=_explainer_agent(),
+    )
+
+    crew = Crew(
+        agents=[_explainer_agent()],
+        tasks=[task],
+        process=Process.sequential,
+        planning=False,
+        verbose=False,
+    )
+
+    result = crew.kickoff()
+    # CrewAI returns text; we enforce JSON-only in prompt
+    try:
+        return json.loads(str(result))
+    except Exception as e:
+        # fallback that doesn't crash UI
+        return {
+            "summary": "",
+            "strengths": [],
+            "gaps": [],
+            "risk_flags": [f"Failed to parse agent output as JSON: {type(e).__name__}: {e}"],
+            "interview_questions": [],
+            "recommended_next_step": "Retry generation."
+        }

core/explainability.py

@@ -0,0 +1,7 @@
+from pathlib import Path
+
+from core.crew_explainer import generate_explanation
+
+def explain_candidate(jd_path: str, match_path: str, rank: int | None = None) -> dict:
+    # You can add caching later if you want (by match_path hash)
+    return generate_explanation(jd_path=jd_path, match_path=match_path, top_k_rank=rank)

core/jd_processor.py

@@ -0,0 +1,64 @@
+# %%writefile core/jd_processor.py
+import logging
+import json
+import os
+from openai import OpenAI, APIError
+from utils.prompts import JD_PROMPT
+
+logger = logging.getLogger(__name__)
+client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+
+def generate_jd_rubric(jd_text, max_retries=3):
+    """Generate JD rubric with retry logic and better error handling."""
+
+    for attempt in range(max_retries):
+        try:
+            response = client.chat.completions.create(
+                model="gpt-4o-mini",
+                messages=[
+                    {"role": "system", "content": "You are an experienced HR Talent Manager AI assistant. Your specialty is analyzing job descriptions and creating structured hiring rubrics."},
+                    {"role": "user", "content": JD_PROMPT.format(jd_text=jd_text)}
+                ],
+                temperature=0.2,
+                response_format={"type": "json_object"}  # New: Force JSON response
+            )
+
+            content = response.choices[0].message.content
+            logger.debug(f"LLM response (attempt {attempt+1}): {content[:200]}...")
+
+            # Parse JSON
+            jd_data = json.loads(content)  # No need for find() with response_format
+
+            # Validate structure
+            required_keys = {"role_title", "must_have_skills", "nice_to_have_skills",
+                           "soft_skills", "minimum_years_experience", "recommended_weights"}
+
+            if not all(key in jd_data for key in required_keys):
+                raise ValueError("Missing required keys in response")
+
+            return jd_data
+
+        except json.JSONDecodeError as e:
+            logger.warning(f"JSON decode failed (attempt {attempt+1}): {e}")
+            if attempt == max_retries - 1:
+                return get_empty_template()
+        except APIError as e:
+            logger.error(f"OpenAI API error: {e}")
+            if attempt == max_retries - 1:
+                return get_empty_template()
+        except Exception as e:
+            logger.error(f"Unexpected error: {e}")
+            return get_empty_template()
+
+    return get_empty_template()
+
+def get_empty_template():
+    """Return empty rubric template."""
+    return {
+        "role_title": "",
+        "must_have_skills": [],
+        "nice_to_have_skills": [],
+        "soft_skills": [],
+        "minimum_years_experience": 0,
+        "recommended_weights": {}
+    }

core/matcher.py

@@ -0,0 +1,32 @@
+# %%writefile core/matcher.py
+import json
+from openai import OpenAI
+from utils.prompts import JD_RESUME_MATCH_PROMPT
+import os
+
+client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+
+def match_candidate_to_jd(jd_rubric, candidate_profile):
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[
+            {
+                "role": "system",
+                "content": JD_RESUME_MATCH_PROMPT
+            },
+            {
+                "role": "user",
+                "content": f"""
+Job Description Rubric:
+{json.dumps(jd_rubric, indent=2)}
+
+Candidate Profile:
+{json.dumps(candidate_profile, indent=2)}
+"""
+            }
+        ],
+        temperature=0.2
+    )
+
+    content = response.choices[0].message.content.strip()
+    return json.loads(content)

core/ranking.py

@@ -0,0 +1,41 @@
+# %%writefile core/ranking.py
+import os
+import json
+from core.scoring import score_candidate
+
+JD_PATH = "data/jd.json"
+MATCH_DIR = "data/matches"
+OUT_PATH = "data/ranking.json"
+
+
+def build_ranking(top_k: int = 10):
+    with open(JD_PATH, "r", encoding="utf-8") as f:
+        jd_rubric = json.load(f)
+
+    rows = []
+    for fname in os.listdir(MATCH_DIR):
+        if not fname.endswith("_match.json"):
+            continue
+
+        fpath = os.path.join(MATCH_DIR, fname)
+        with open(fpath, "r", encoding="utf-8") as f:
+            match_summary = json.load(f)
+
+        scored = score_candidate(jd_rubric, match_summary)
+        scored["match_file"] = fname
+        rows.append(scored)
+
+    rows.sort(key=lambda x: x["total_score"], reverse=True)
+
+    result = {
+        "jd_role_title": jd_rubric.get("role_title", ""),
+        "top_k": top_k,
+        "ranking": rows[:top_k],
+        "all_candidates": rows
+    }
+
+    with open(OUT_PATH, "w", encoding="utf-8") as f:
+        json.dump(result, f, indent=2)
+
+    return result
+

core/resume_parser.py

@@ -0,0 +1,50 @@
+# added Step1 patch, added parser_error.log
+import os
+import json
+from datetime import datetime
+
+from openai import OpenAI
+from utils.prompts import RESUME_PARSE_PROMPT
+
+client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+
+
+def _append_log(path: str, line: str) -> None:
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    with open(path, "a", encoding="utf-8") as f:
+        f.write(line.rstrip("\n") + "\n")
+
+
+def parse_resume(resume_text, filename):
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[
+            {"role": "system", "content": "You are an expert HR resume analyst specializing in extracting structured information from resumes with high accuracy."},
+            {"role": "user", "content": RESUME_PARSE_PROMPT.format(resume_text=resume_text)}
+        ],
+        temperature=0.2
+    )
+
+    content = response.choices[0].message.content
+
+    try:
+        start = content.find("{")
+        end = content.rfind("}") + 1
+        json_str = content[start:end]
+        data = json.loads(json_str)
+    except Exception as e:
+        ts = datetime.now().isoformat(timespec="seconds")
+        msg = f"{ts} | {filename} | {type(e).__name__}: {e} | content_len={len(content)}"
+        _append_log("data/parse_errors.log", msg)
+
+        data = {
+            "name": "",
+            "skills": [],
+            "education": [],
+            "work_experience": [],
+            "total_years_experience": 0,
+            "summary": ""
+        }
+
+    data["candidate_id"] = filename
+    return data

core/scoring.py

@@ -0,0 +1,113 @@
+# %%writefile core/scoring.py
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Dict, Any, List
+
+
+def _safe_len(x) -> int:
+    return len(x) if isinstance(x, list) else 0
+
+
+def normalize_weights(weights: Dict[str, Any]) -> Dict[str, float]:
+    w_must = float(weights.get("must_have", 0))
+    w_nice = float(weights.get("nice_to_have", 0))
+    w_exp = float(weights.get("experience", 0))
+    w_soft = float(weights.get("soft_skills", 0))
+
+    total = w_must + w_nice + w_exp + w_soft
+    if total <= 0:
+        return {"must_have": 0.6, "nice_to_have": 0.25, "experience": 0.15, "soft_skills": 0.0}
+
+    return {
+        "must_have": w_must / total,
+        "nice_to_have": w_nice / total,
+        "experience": w_exp / total,
+        "soft_skills": w_soft / total
+    }
+
+
+def compute_coverage(matched: List[Any], missing: List[Any], partial: List[Any] | None = None) -> float:
+    m = _safe_len(matched)
+    miss = _safe_len(missing)
+    p = _safe_len(partial) if partial is not None else 0
+
+    denom = m + miss + p
+    if denom == 0:
+        return 0.0
+
+    return (m + 0.5 * p) / denom
+
+
+def experience_score(assessment: str) -> float:
+    assessment = (assessment or "").strip().lower()
+    if assessment == "below":
+        return 0.0
+    if assessment in ("meets", "exceeds"):
+        return 1.0
+    return 0.0
+
+
+def clamp(x: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, x))
+
+
+def score_candidate(jd_rubric: Dict[str, Any], match_summary: Dict[str, Any]) -> Dict[str, Any]:
+    weights = normalize_weights(jd_rubric.get("recommended_weights", {}))
+
+    mh = match_summary.get("must_have_match", {}) or {}
+    nh = match_summary.get("nice_to_have_match", {}) or {}
+    exp = match_summary.get("experience_analysis", {}) or {}
+
+    must_cov = compute_coverage(
+        matched=mh.get("matched", []),
+        missing=mh.get("missing", []),
+        partial=mh.get("partial", [])
+    )
+
+    nice_cov = compute_coverage(
+        matched=nh.get("matched", []),
+        missing=nh.get("missing", []),
+        partial=None
+    )
+
+    exp_sc = experience_score(exp.get("assessment", ""))
+
+    # Soft skills scoring (optional). Keep 0 for student MVP unless you add logic later.
+    soft_sc = 0.0
+
+    base_total = (
+        weights["must_have"] * must_cov +
+        weights["nice_to_have"] * nice_cov +
+        weights["experience"] * exp_sc +
+        weights["soft_skills"] * soft_sc
+    ) * 100.0
+
+    # ✅ Bonus/Penalty based on Step-4 indicators (transparent & capped)
+    positives = match_summary.get("positive_indicators", []) or []
+    negatives = match_summary.get("negative_indicators", []) or []
+
+    bonus_per_positive = 1.0
+    penalty_per_negative = 1.5
+    raw_adjustment = (len(positives) * bonus_per_positive) - (len(negatives) * penalty_per_negative)
+
+    # Cap adjustment so it doesn't dominate scoring
+    adjustment_cap = 8.0
+    adjustment = clamp(raw_adjustment, -adjustment_cap, adjustment_cap)
+
+    final_total = clamp(base_total + adjustment, 0.0, 100.0)
+
+    return {
+        "candidate_name": match_summary.get("candidate_name", ""),
+        "total_score": round(final_total, 2),
+        "breakdown": {
+            "base_score": round(base_total, 2),
+            "bonus_penalty_adjustment": round(adjustment, 2),
+            "positive_count": len(positives),
+            "negative_count": len(negatives),
+            "must_have_coverage": round(must_cov, 3),
+            "nice_to_have_coverage": round(nice_cov, 3),
+            "experience_score": round(exp_sc, 3),
+            "weights_normalized": weights
+        }
+    }
+

requirements.txt

@@ -0,0 +1,18 @@
+# from pip freeze
+
+gradio==5.50.0
+numpy==2.0.2
+pandas==2.2.2
+openai==2.12.0
+pydantic==2.12.3
+PyPDF2==3.0.1
+python-docx==1.2.0
+python-dotenv==1.2.1
+tqdm==4.67.1
+crewai==0.175.0
+
+# Colab already have both numpy 2.0.2 and pandas 2.2.2 installed.
+# !pip install -r requirements.txt
+# pip freeze > requirements.txt
+# added pandas==2.2.2
+# added crewai==0.175.0

utils/__init__.py

@@ -0,0 +1,2 @@
+# utils/__init__.py
+# core/__init__.py

utils/file_loader.py

@@ -0,0 +1,36 @@
+# %%writefile file_loader.py
+from PyPDF2 import PdfReader
+from docx import Document
+
+
+def load_text_from_file(uploaded_file):
+    if "." not in uploaded_file.name:
+        raise ValueError("File has no extension")
+
+    file_type = uploaded_file.name.split(".")[-1].lower()
+
+    try:
+        if file_type == "pdf":
+            reader = PdfReader(uploaded_file)
+            return "\n".join([page.extract_text() for page in reader.pages])
+
+        elif file_type in ["docx", "doc"]:
+            doc = Document(uploaded_file)
+            return "\n".join([para.text for para in doc.paragraphs])
+
+        elif file_type == "txt":
+            content = uploaded_file.read()
+            for encoding in ["utf-8", "latin-1", "cp1252"]:
+                try:
+                    return content.decode(encoding)
+                except UnicodeDecodeError:
+                    continue
+            raise ValueError("Unable to decode text file")
+
+        else:
+            raise ValueError(f"Unsupported file type: {file_type}")
+
+    except ImportError as e:
+        raise ImportError(f"Required library not installed: {e}")
+    except Exception as e:
+        raise ValueError(f"Error processing file: {e}")

utils/prompts.py

@@ -0,0 +1,84 @@
+# %%writefile utils/prompts.py
+JD_PROMPT = """
+Given the following Job Description, extract a structured hiring rubric.
+
+Return STRICT JSON with the following fields:
+- role_title
+- must_have_skills (list)
+- nice_to_have_skills (list)
+- soft_skills (list)
+- minimum_years_experience (number)
+- minimum education requirements (list)
+- recommended_weights (object with must_have, nice_to_have, experience, education, soft_skills)
+
+Job Description:
+----------------
+{jd_text}
+"""
+
+RESUME_PARSE_PROMPT = """
+You are an experienced HR resume analyst.
+
+Given the following resume text, extract a structured candidate profile.
+
+Return STRICT JSON with these fields:
+- name
+- technical skills (list)
+- soft skills (list)
+- education (list)
+- work_experience (list of short role summaries)
+- total_years_experience (number)
+- summary (2–3 sentence professional summary)
+
+Resume Text:
+-------------
+{resume_text}
+
+IMPORTANT:
+- Output JSON only
+- Do not include explanations
+"""
+
+JD_RESUME_MATCH_PROMPT = """
+You are an experienced HR hiring analyst.
+
+You will be given:
+1. A structured Job Description rubric (JSON)
+2. A structured candidate profile (JSON)
+
+Your task:
+- Compare the candidate against the JD rubric
+- Identify matches, partial matches, and gaps
+- Identify positive and negative indicators
+- DO NOT calculate a score
+- Be factual and conservative
+- Do NOT infer sensitive personal attributes
+- Output ONLY valid JSON in the specified schema
+
+Matching rules:
+- A skill is matched if clearly demonstrated in experience or skills
+- Partial if loosely related or implied
+- Missing if not found
+
+Output JSON schema:
+{
+  "candidate_name": "",
+  "must_have_match": {
+    "matched": [],
+    "missing": [],
+    "partial": []
+  },
+  "nice_to_have_match": {
+    "matched": [],
+    "missing": []
+  },
+  "experience_analysis": {
+    "required_years": 0,
+    "candidate_years": 0,
+    "assessment": "below | meets | exceeds"
+  },
+  "positive_indicators": [],
+  "negative_indicators": [],
+  "overall_fit_summary": ""
+}
+"""

utils/resume_loader.py

@@ -0,0 +1,11 @@
+# %%writefile utils/resume_loader.py
+import os
+
+def load_resume_files(resume_dir="data/resumes"):
+    return [
+        os.path.join(resume_dir, f)
+        for f in os.listdir(resume_dir)
+        if os.path.isfile(os.path.join(resume_dir, f))
+        and f.lower().endswith((".pdf", ".docx", ".txt"))
+        and not f.startswith(".")
+    ]