Upload 16 files

.gitignore

@@ -0,0 +1,13 @@
+.env
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+.DS_Store
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.log

README.md

@@ -1,12 +1,88 @@
 ---
-title: Coderound Bkl
-emoji: 🌍
-colorFrom: yellow
-colorTo: pink
+title: AI Recruitment Agent
+emoji: ⚡
+colorFrom: indigo
+colorTo: green
 sdk: gradio
-sdk_version: 6.12.0
+sdk_version: "4.44.0"
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ⚡ AI Recruitment Agent
+
+A production-grade hybrid candidate matching pipeline using **Groq LLM**, **Pinecone vector DB**, and a **Gradio** UI.
+
+## Architecture
+
+```
+CSV Input → Stage 1: Normalize (Groq)
+          → Stage 2: Embed + Match (Pinecone + SentenceTransformers) → Top 20
+          → Stage 3: Deterministic Rerank (Groq) → Top 10
+          → Stage 4: LLM Deep Review (Groq) → Top 5
+          → Stage 5: Final Synthesis (Groq) → Shortlist
+```
+
+## Setup (Local)
+
+### 1. Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Configure environment
+
+```bash
+cp .env.example .env
+# Edit .env and fill in your API keys
+```
+
+### 3. Create Pinecone index
+
+In your Pinecone console:
+- Create an index named `recruitment-index` (or whatever you set in `PINECONE_INDEX`)
+- Dimension: **384** for `all-MiniLM-L6-v2`, **1024** for `BAAI/bge-m3`
+- Metric: **cosine**
+
+### 4. Run
+
+```bash
+python app.py
+```
+
+Open http://localhost:7860
+
+## Setup (Hugging Face Spaces)
+
+Do **not** commit a `.env` file. Instead, go to your Space → **Settings → Repository Secrets** and add:
+
+| Secret | Example value |
+|--------|--------------|
+| `GROQ_API_KEYS` | `gsk_xxx,gsk_yyy` |
+| `GROQ_MODEL` | `llama3-70b-8192` |
+| `PINECONE_API_KEY` | `pcsk_xxx` |
+| `PINECONE_INDEX` | `recruitment-index` |
+| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` |
+| `STAGE2_TOP_K` | `20` |
+
+## CSV Format
+
+| Column | Variants accepted |
+|--------|----------|
+| `name` | `full_name`, `candidate_name` |
+| `email` | `email_address` |
+| `skills` | `parsed_skills`, `technical_skills` |
+| `experience` | `parsed_work_experience`, `years_of_experience` |
+| `education` | `parsed_metadata_education` |
+| `resume_text` | `parsed_summary`, `summary` |
+
+## Pipeline Stages
+
+| Stage | Method | Input | Output |
+|-------|--------|-------|--------|
+| 1. Normalize | Groq LLM | All candidates | Structured features |
+| 2. Embed & Match | Pinecone + SentenceTransformers | All candidates | Top 20 by similarity |
+| 3. Rerank | Groq LLM (deterministic scoring) | Top 20 | Top 10 with scores |
+| 4. Deep Review | Groq LLM | Top 5 | Verdicts + signals |
+| 5. Final Synthesis | Groq LLM | Top 5 reviews | Final ranked shortlist |

ai-recruitment-agent.zip

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

app.py

@@ -0,0 +1,713 @@
+"""
+AI Recruitment Matching Agent — Gradio 4.16.0 UI
+Run: python gradio_app.py
+"""
+
+import os
+import asyncio
+import uuid
+import io
+import json
+import threading
+from typing import List, Optional
+from dotenv import load_dotenv
+
+load_dotenv()
+
+import pandas as pd
+import gradio as gr
+
+from app.models.schemas import Candidate, EvaluationResponse
+from app.services.evaluation_service import perform_hybrid_evaluation
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+VERDICT_EMOJI = {
+    "strong hire": "🟢",
+    "hire": "🟡",
+    "consider": "🟠",
+    "reject": "🔴",
+}
+
+DECISION_COLOR = {
+    "strong hire": "#22c55e",
+    "hire": "#eab308",
+    "consider": "#f97316",
+    "reject": "#ef4444",
+}
+
+SAMPLE_JD = """Backend Engineer — SaaS Platform
+
+We are seeking a Backend Engineer to design and build the core infrastructure of our SaaS platform. The role involves developing scalable microservices, building APIs, and managing IoT data pipelines.
+
+Core Requirements:
+- Minimum 3 years of experience in backend development
+- Strong proficiency in Node.js
+- Experience with FastAPI, Django, or Express
+- Strong understanding of RESTful APIs and microservices
+- Experience with relational and/or NoSQL databases
+
+Preferred:
+- Experience with AWS, GCP, or Azure
+- Docker, Kubernetes, CI/CD pipelines
+- Redis, Kafka or RabbitMQ
+- Startup experience
+
+Skills: Backend Engineer, Node.js, AWS, Microservices, IoT, SaaS, Serverless, API Development"""
+
+
+def parse_csv_to_candidates(filepath: str) -> tuple[List[Candidate], pd.DataFrame, str]:
+    """Parse uploaded CSV into Candidate objects. Returns (candidates, df, error)."""
+    try:
+        df = pd.read_csv(filepath).fillna("")
+        candidates = []
+
+        # Smart column detection
+        col_map = {col.lower().strip(): col for col in df.columns}
+
+        def get_col(candidates_list):
+            for c in candidates_list:
+                if c in col_map:
+                    return col_map[c]
+            return None
+
+        name_col = get_col(["name", "full_name", "candidate_name"])
+        email_col = get_col(["email", "email_address"])
+        skills_col = get_col(["skills", "parsed_skills", "technical_skills"])
+        exp_col = get_col(["experience", "parsed_work_experience", "work_experience", "years_of_experience"])
+        proj_col = get_col(["projects", "parsed_projects"])
+        edu_col = get_col(["education", "parsed_metadata_education", "education_status"])
+        resume_col = get_col(["resume_text", "parsed_summary", "summary", "resume"])
+
+        for _, row in df.iterrows():
+            candidates.append(Candidate(
+                id=str(uuid.uuid4()),
+                name=str(row[name_col]) if name_col else "Unknown",
+                email=str(row[email_col]) if email_col else "",
+                skills=str(row[skills_col]) if skills_col else "",
+                experience=str(row[exp_col]) if exp_col else "",
+                projects=str(row[proj_col]) if proj_col else "",
+                education=str(row[edu_col]) if edu_col else "",
+                resume_text=str(row[resume_col]) if resume_col else "",
+            ))
+
+        return candidates, df, ""
+    except Exception as e:
+        return [], pd.DataFrame(), f"Error parsing CSV: {e}"
+
+
+def build_shortlist_table(response: EvaluationResponse) -> pd.DataFrame:
+    rows = []
+    for rank in response.shortlist:
+        detail = response.details.get(rank.candidate_id, {})
+        emoji = VERDICT_EMOJI.get(rank.decision.lower(), "⚪")
+        rows.append({
+            "Rank": rank.rank,
+            "Name": rank.name,
+            "Decision": f"{emoji} {rank.decision.title()}",
+            "Confidence": f"{int(detail.get('confidence', 0) * 100)}%",
+            "Why": rank.reason,
+            "Strengths": " | ".join(detail.get("strengths", [])),
+            "Risks": " | ".join(detail.get("risks", [])),
+            "Signal": detail.get("hidden_signal", ""),
+        })
+    return pd.DataFrame(rows)
+
+
+def build_detail_md(response: EvaluationResponse, shortlist_df: pd.DataFrame) -> str:
+    md_parts = []
+    for rank in response.shortlist:
+        detail = response.details.get(rank.candidate_id, {})
+        emoji = VERDICT_EMOJI.get((detail.get("verdict") or rank.decision).lower(), "⚪")
+        verdict = (detail.get("verdict") or rank.decision).title()
+        confidence_pct = int(detail.get("confidence", 0) * 100)
+
+        md_parts.append(f"""
+### {rank.rank}. {rank.name}  {emoji} {verdict}
+
+**Why:** {detail.get("why", rank.reason)}
+
+**Confidence:** {confidence_pct}%
+
+**Strengths:**
+{chr(10).join(f"- {s}" for s in detail.get("strengths", []))}
+
+**Risks:**
+{chr(10).join(f"- {r}" for r in detail.get("risks", []))}
+
+**Hidden Signal:** _{detail.get("hidden_signal", "—")}_
+
+---
+""")
+    return "\n".join(md_parts) if md_parts else "_No results yet._"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Core async runner
+# ─────────────────────────────────────────────────────────────────────────────
+
+def run_evaluation_sync(jd: str, candidates: List[Candidate], log_queue: list):
+    """Run async pipeline in a thread-safe way."""
+    def progress_cb(msg: str):
+        log_queue.append(msg)
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        result = loop.run_until_complete(
+            perform_hybrid_evaluation(jd, candidates, progress_cb=progress_cb)
+        )
+        return result, None
+    except Exception as e:
+        return None, str(e)
+    finally:
+        loop.close()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Gradio App
+# ─────────────────────────────────────────────────────────────────────────────
+
+CSS = """
+/* ── Root & Typography ── */
+@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&family=Syne:wght@400;700;800&display=swap');
+
+:root {
+    --bg: #0a0a0f;
+    --surface: #12121a;
+    --border: #1e1e2e;
+    --accent: #6ee7b7;
+    --accent2: #818cf8;
+    --warn: #fbbf24;
+    --danger: #f87171;
+    --text: #e2e8f0;
+    --muted: #64748b;
+    --radius: 8px;
+}
+
+body, .gradio-container {
+    background: var(--bg) !important;
+    font-family: 'Syne', sans-serif !important;
+    color: var(--text) !important;
+}
+
+/* Header */
+.app-header {
+    background: linear-gradient(135deg, #0f172a 0%, #1e1b4b 50%, #0f172a 100%);
+    border-bottom: 1px solid var(--accent2);
+    padding: 24px 32px;
+    margin-bottom: 0;
+}
+.app-header h1 {
+    font-family: 'Syne', sans-serif;
+    font-weight: 800;
+    font-size: 2rem;
+    color: var(--accent);
+    margin: 0;
+    letter-spacing: -0.5px;
+}
+.app-header p {
+    color: var(--muted);
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.78rem;
+    margin: 4px 0 0;
+}
+
+/* Panels */
+.panel {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 20px;
+}
+
+/* Labels */
+label span {
+    font-family: 'IBM Plex Mono', monospace !important;
+    font-size: 0.72rem !important;
+    color: var(--accent2) !important;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+}
+
+/* Textboxes */
+textarea, input[type="text"] {
+    background: #0d0d16 !important;
+    border: 1px solid var(--border) !important;
+    border-radius: var(--radius) !important;
+    color: var(--text) !important;
+    font-family: 'IBM Plex Mono', monospace !important;
+    font-size: 0.82rem !important;
+}
+textarea:focus, input:focus {
+    border-color: var(--accent2) !important;
+    box-shadow: 0 0 0 2px rgba(129, 140, 248, 0.15) !important;
+}
+
+/* Buttons */
+button.primary {
+    background: linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%) !important;
+    color: white !important;
+    border: none !important;
+    border-radius: var(--radius) !important;
+    font-family: 'Syne', sans-serif !important;
+    font-weight: 700 !important;
+    font-size: 0.95rem !important;
+    padding: 12px 28px !important;
+    transition: all 0.2s ease !important;
+    letter-spacing: 0.02em;
+}
+button.primary:hover {
+    transform: translateY(-1px) !important;
+    box-shadow: 0 4px 20px rgba(124, 58, 237, 0.4) !important;
+}
+button.secondary {
+    background: transparent !important;
+    border: 1px solid var(--border) !important;
+    color: var(--muted) !important;
+    border-radius: var(--radius) !important;
+    font-family: 'IBM Plex Mono', monospace !important;
+    font-size: 0.8rem !important;
+}
+button.secondary:hover {
+    border-color: var(--accent2) !important;
+    color: var(--accent2) !important;
+}
+
+/* Log box */
+.log-box textarea {
+    font-family: 'IBM Plex Mono', monospace !important;
+    font-size: 0.75rem !important;
+    color: var(--accent) !important;
+    background: #050508 !important;
+    border-color: #1a1a2e !important;
+    line-height: 1.6;
+}
+
+/* Dataframe */
+.dataframe th {
+    background: #1a1a2e !important;
+    color: var(--accent2) !important;
+    font-family: 'IBM Plex Mono', monospace !important;
+    font-size: 0.72rem !important;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+}
+.dataframe td {
+    font-family: 'IBM Plex Mono', monospace !important;
+    font-size: 0.8rem !important;
+    color: var(--text) !important;
+    border-color: var(--border) !important;
+}
+
+/* Status badge */
+.status-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 12px;
+    border-radius: 20px;
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.75rem;
+    font-weight: 600;
+}
+
+/* Tabs */
+.tab-nav button {
+    font-family: 'IBM Plex Mono', monospace !important;
+    font-size: 0.8rem !important;
+    color: var(--muted) !important;
+    border-bottom: 2px solid transparent !important;
+    background: transparent !important;
+}
+.tab-nav button.selected {
+    color: var(--accent) !important;
+    border-bottom-color: var(--accent) !important;
+}
+
+/* Markdown output */
+.markdown-body {
+    font-family: 'Syne', sans-serif;
+    color: var(--text);
+    line-height: 1.7;
+}
+.markdown-body h3 {
+    color: var(--accent2);
+    font-size: 1.05rem;
+    margin-top: 24px;
+}
+.markdown-body strong {
+    color: var(--accent);
+}
+.markdown-body hr {
+    border-color: var(--border);
+}
+
+/* Pipeline steps */
+.pipeline-step {
+    display: inline-block;
+    padding: 3px 10px;
+    margin: 2px;
+    border-radius: 4px;
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.7rem;
+    background: #1a1a2e;
+    color: var(--accent2);
+    border: 1px solid #2d2d5e;
+}
+
+/* Accent divider */
+.divider {
+    height: 2px;
+    background: linear-gradient(90deg, var(--accent2), transparent);
+    margin: 16px 0;
+    border: none;
+}
+"""
+
+
+def create_app():
+    with gr.Blocks(
+        css=CSS,
+        title="AI Recruitment Agent",
+        theme=gr.themes.Base(
+            primary_hue="violet",
+            neutral_hue="slate",
+        ),
+    ) as app:
+
+        # ── State ──────────────────────────────────────────────
+        candidates_state = gr.State([])
+        response_state = gr.State(None)
+
+        # ── Header ─────────────────────────────────────────────
+        gr.HTML("""
+        <div class="app-header">
+            <h1>⚡ AI Recruitment Agent</h1>
+            <p>5-stage hybrid pipeline · Groq LLM · Pinecone embeddings · Deterministic reranking</p>
+        </div>
+        <div style="display:flex; gap:8px; padding:12px 32px; background:#0c0c14; border-bottom:1px solid #1e1e2e;">
+            <span class="pipeline-step">① Normalize</span>
+            <span style="color:#64748b;align-self:center">→</span>
+            <span class="pipeline-step">② Embed</span>
+            <span style="color:#64748b;align-self:center">→</span>
+            <span class="pipeline-step">③ Rerank</span>
+            <span style="color:#64748b;align-self:center">→</span>
+            <span class="pipeline-step">④ Deep Review</span>
+            <span style="color:#64748b;align-self:center">→</span>
+            <span class="pipeline-step">⑤ Shortlist</span>
+        </div>
+        """)
+
+        # ── Main Layout ────────────────────────────────────────
+        with gr.Row(equal_height=False):
+
+            # Left column — inputs
+            with gr.Column(scale=4, min_width=360):
+                gr.HTML('<div style="height:16px"></div>')
+
+                # JD input
+                jd_input = gr.Textbox(
+                    label="📋 Job Description",
+                    placeholder="Paste the full job description here...",
+                    lines=14,
+                    value=SAMPLE_JD,
+                    elem_classes=["panel"],
+                )
+
+                gr.HTML('<div style="height:12px"></div>')
+
+                # CSV upload
+                csv_upload = gr.File(
+                    label="📂 Upload Candidates CSV",
+                    file_types=[".csv"],
+                    elem_classes=["panel"],
+                )
+
+                # Candidate count badge
+                candidate_count = gr.HTML(
+                    '<div style="color:#64748b; font-family:\'IBM Plex Mono\',monospace; font-size:0.75rem; padding:6px 0;">No candidates loaded</div>'
+                )
+
+                gr.HTML('<div style="height:12px"></div>')
+
+                # Preview table
+                preview_table = gr.Dataframe(
+                    label="👥 Candidate Preview",
+                    headers=["Name", "Email", "Skills Preview"],
+                    datatype=["str", "str", "str"],
+                    visible=False,
+                    wrap=True,
+                    elem_classes=["panel"],
+                )
+
+                gr.HTML('<div style="height:16px"></div>')
+
+                # Action buttons
+                with gr.Row():
+                    run_btn = gr.Button(
+                        "🚀 Run Evaluation",
+                        variant="primary",
+                        scale=3,
+                    )
+                    clear_btn = gr.Button(
+                        "↺ Reset",
+                        variant="secondary",
+                        scale=1,
+                    )
+
+            # Right column — outputs
+            with gr.Column(scale=6, min_width=500):
+                gr.HTML('<div style="height:16px"></div>')
+
+                with gr.Tabs(elem_classes=["tab-nav"]):
+
+                    # Tab 1 — Live Log
+                    with gr.Tab("📡 Live Pipeline Log"):
+                        log_output = gr.Textbox(
+                            label="",
+                            lines=18,
+                            interactive=False,
+                            placeholder="Pipeline logs will appear here...",
+                            elem_classes=["log-box"],
+                        )
+
+                    # Tab 2 — Results Table
+                    with gr.Tab("🏆 Shortlist"):
+                        status_html = gr.HTML(
+                            '<div style="color:#64748b;font-family:\'IBM Plex Mono\',monospace;font-size:0.8rem;padding:8px 0;">Run evaluation to see results.</div>'
+                        )
+                        results_table = gr.Dataframe(
+                            label="Final Shortlist",
+                            wrap=True,
+                            elem_classes=["panel"],
+                        )
+
+                    # Tab 3 — Deep Reviews
+                    with gr.Tab("🔍 Deep Reviews"):
+                        detail_output = gr.Markdown(
+                            value="_Run evaluation to see candidate deep reviews._",
+                        )
+
+                    # Tab 4 — Raw JSON
+                    with gr.Tab("{ } Raw JSON"):
+                        raw_json_output = gr.Code(
+                            language="json",
+                            label="Full API Response",
+                            lines=30,
+                        )
+
+        # ── Event Handlers ──────────────────────────────────────
+
+        def on_csv_upload(file):
+            if file is None:
+                return (
+                    [],
+                    '<div style="color:#64748b;font-family:\'IBM Plex Mono\',monospace;font-size:0.75rem;padding:6px 0;">No candidates loaded</div>',
+                    gr.update(visible=False),
+                    pd.DataFrame(),
+                )
+
+            candidates, df, err = parse_csv_to_candidates(file.name)
+            if err:
+                return (
+                    [],
+                    f'<div style="color:#f87171;font-family:\'IBM Plex Mono\',monospace;font-size:0.75rem;padding:6px 0;">⚠ {err}</div>',
+                    gr.update(visible=False),
+                    pd.DataFrame(),
+                )
+
+            count = len(candidates)
+            badge_color = "#22c55e" if count > 0 else "#f87171"
+            badge = f'<div style="color:{badge_color};font-family:\'IBM Plex Mono\',monospace;font-size:0.75rem;padding:6px 0;">✓ {count} candidates loaded from CSV</div>'
+
+            # Build preview
+            preview_rows = []
+            for c in candidates[:10]:
+                skills_preview = (c.skills or "")[:80] + ("..." if len(c.skills or "") > 80 else "")
+                preview_rows.append([c.name, c.email or "—", skills_preview])
+            preview_df = pd.DataFrame(preview_rows, columns=["Name", "Email", "Skills Preview"])
+
+            return candidates, badge, gr.update(visible=True), preview_df
+
+        csv_upload.change(
+            fn=on_csv_upload,
+            inputs=[csv_upload],
+            outputs=[candidates_state, candidate_count, preview_table, preview_table],
+        )
+
+        def on_run(jd: str, candidates: list):
+            if not jd.strip():
+                yield (
+                    "⚠ Please enter a Job Description.",
+                    gr.update(),
+                    "_No results yet._",
+                    "{}",
+                    '<div style="color:#f87171;font-size:0.8rem;">Job description required.</div>',
+                    None,
+                )
+                return
+
+            if not candidates:
+                yield (
+                    "⚠ Please upload a CSV file with candidates first.",
+                    gr.update(),
+                    "_No results yet._",
+                    "{}",
+                    '<div style="color:#f87171;font-size:0.8rem;">No candidates loaded.</div>',
+                    None,
+                )
+                return
+
+            log_queue = []
+            result_holder = [None]
+            error_holder = [None]
+
+            # Run in thread
+            def run():
+                res, err = run_evaluation_sync(jd, candidates, log_queue)
+                result_holder[0] = res
+                error_holder[0] = err
+
+            thread = threading.Thread(target=run)
+            thread.start()
+
+            # Stream logs while running
+            import time
+            last_log_len = 0
+            while thread.is_alive():
+                time.sleep(0.5)
+                if len(log_queue) > last_log_len:
+                    last_log_len = len(log_queue)
+                    log_text = "\n".join(log_queue)
+                    yield (
+                        log_text,
+                        gr.update(),
+                        "_Processing..._",
+                        "{}",
+                        '<div style="color:#818cf8;font-size:0.8rem;font-family:\'IBM Plex Mono\',monospace;">⏳ Evaluating candidates...</div>',
+                        None,
+                    )
+
+            thread.join()
+
+            final_logs = "\n".join(log_queue)
+
+            if error_holder[0]:
+                yield (
+                    final_logs + f"\n\n❌ ERROR: {error_holder[0]}",
+                    gr.update(),
+                    "_Evaluation failed._",
+                    "{}",
+                    f'<div style="color:#f87171;font-size:0.8rem;">❌ {error_holder[0]}</div>',
+                    None,
+                )
+                return
+
+            response: EvaluationResponse = result_holder[0]
+
+            # Build outputs
+            shortlist_df = build_shortlist_table(response)
+            detail_md = build_detail_md(response, shortlist_df)
+            raw_json = json.dumps(response.model_dump(), indent=2)
+
+            n = len(response.shortlist)
+            top = response.shortlist[0] if response.shortlist else None
+            top_name = top.name if top else "—"
+            top_decision = top.decision if top else "—"
+            emoji = VERDICT_EMOJI.get((top_decision or "").lower(), "⚪")
+
+            status = f'''
+            <div style="display:flex;gap:16px;align-items:center;padding:8px 0;">
+                <div style="color:#22c55e;font-family:'IBM Plex Mono',monospace;font-size:0.8rem;">
+                    ✓ Evaluation complete · {n} candidates shortlisted
+                </div>
+                <div style="color:#64748b;font-family:'IBM Plex Mono',monospace;font-size:0.8rem;">
+                    Top pick: <span style="color:#e2e8f0">{top_name}</span> {emoji}
+                </div>
+            </div>
+            '''
+
+            yield (
+                final_logs + "\n\n✅ Evaluation complete.",
+                shortlist_df,
+                detail_md,
+                raw_json,
+                status,
+                response,
+            )
+
+        run_btn.click(
+            fn=on_run,
+            inputs=[jd_input, candidates_state],
+            outputs=[
+                log_output,
+                results_table,
+                detail_output,
+                raw_json_output,
+                status_html,
+                response_state,
+            ],
+        )
+
+        def on_clear():
+            return (
+                [],
+                SAMPLE_JD,
+                None,
+                "",
+                pd.DataFrame(),
+                "_No results yet._",
+                "{}",
+                '<div style="color:#64748b;font-family:\'IBM Plex Mono\',monospace;font-size:0.75rem;padding:6px 0;">No candidates loaded</div>',
+                gr.update(visible=False),
+                pd.DataFrame(),
+                '<div style="color:#64748b;font-size:0.8rem;font-family:\'IBM Plex Mono\',monospace;">Run evaluation to see results.</div>',
+            )
+
+        clear_btn.click(
+            fn=on_clear,
+            outputs=[
+                candidates_state,
+                jd_input,
+                csv_upload,
+                log_output,
+                results_table,
+                detail_output,
+                raw_json_output,
+                candidate_count,
+                preview_table,
+                preview_table,
+                status_html,
+            ],
+        )
+
+        # ── Footer ─────────────────────────────────────────────
+        gr.HTML("""
+        <div style="text-align:center;padding:20px;color:#334155;font-family:'IBM Plex Mono',monospace;font-size:0.7rem;border-top:1px solid #1e1e2e;margin-top:24px;">
+            AI Recruitment Agent · Groq + Pinecone + SentenceTransformers · Gradio 4.16.0
+        </div>
+        """)
+
+    return app
+
+
+if __name__ == "__main__":
+    share = os.getenv("GRADIO_SHARE", "false").lower() == "true"
+    port = int(os.getenv("GRADIO_PORT", "7860"))
+
+    print(f"\n{'='*50}")
+    print("  AI Recruitment Agent")
+    print(f"  Starting on http://0.0.0.0:{port}")
+    print(f"  Public share: {share}")
+    print(f"{'='*50}\n")
+
+    app = create_app()
+    app.queue().launch(
+        server_name="0.0.0.0",
+        server_port=port,
+        share=share,
+        show_error=True,
+    )

app/models/schemas.py

@@ -0,0 +1,71 @@
+from pydantic import BaseModel
+from typing import List, Optional, Dict, Any
+
+
+class Candidate(BaseModel):
+    id: str
+    name: str
+    email: Optional[str] = None
+    skills: Optional[str] = None
+    experience: Optional[str] = None
+    projects: Optional[str] = None
+    education: Optional[str] = None
+    resume_text: Optional[str] = None
+    data: Optional[Dict[str, Any]] = None
+
+
+class NormalizedCandidate(BaseModel):
+    candidate_id: str
+    name: str
+    normalized_title: str
+    experience_years: float
+    primary_skills: List[str]
+    secondary_skills: List[str]
+    backend_score: float
+    frontend_score: float
+    cloud_score: float
+    database_score: float
+    notice_period_days: int
+    location: str
+    employment_status: str
+    salary_expectation: str
+    flags: List[str]
+
+
+class RerankResult(BaseModel):
+    candidate_id: str
+    scores: Dict[str, float]
+    final_score: float
+    decision: str
+
+
+class DeepReview(BaseModel):
+    candidate_id: str
+    verdict: str
+    why: str
+    strengths: List[str]
+    risks: List[str]
+    hidden_signal: str
+    confidence: float
+
+
+class FinalRank(BaseModel):
+    rank: int
+    candidate_id: str
+    name: str
+    decision: str
+    reason: str
+
+
+class FinalShortlist(BaseModel):
+    final_ranking: List[FinalRank]
+
+
+class EvaluationRequest(BaseModel):
+    jd: str
+    candidates: List[Candidate]
+
+
+class EvaluationResponse(BaseModel):
+    shortlist: List[FinalRank]
+    details: Dict[str, Any]

app/prompts/templates.py

@@ -0,0 +1,133 @@
+STAGE1_NORMALIZATION_PROMPT = """
+You are a candidate normalization system. Your ONLY job is to extract and clean structured fields from raw candidate data.
+
+JOB DESCRIPTION:
+{jd}
+
+CANDIDATE RAW DATA (JSON):
+{candidate_raw}
+
+RULES:
+- Output ONLY valid JSON. No markdown, no explanation, no preamble.
+- Do not hallucinate any information not present in the data.
+- Standardize all values (e.g., notice period → integer days).
+- Score backend/frontend/cloud/database from 0-10 based on skills in the candidate data vs JD requirements.
+- flags: list any concerns like "No cloud experience", "Very junior", "Mismatch in title", etc.
+
+OUTPUT JSON (exactly this schema):
+{{
+  "candidate_id": "{candidate_id}",
+  "name": "",
+  "normalized_title": "",
+  "experience_years": 0.0,
+  "primary_skills": [],
+  "secondary_skills": [],
+  "backend_score": 0,
+  "frontend_score": 0,
+  "cloud_score": 0,
+  "database_score": 0,
+  "notice_period_days": 0,
+  "location": "",
+  "employment_status": "",
+  "salary_expectation": "",
+  "flags": []
+}}
+"""
+
+STAGE3_RERANK_PROMPT = """
+You are a deterministic candidate scoring engine.
+
+JOB DESCRIPTION:
+{jd}
+
+NORMALIZED CANDIDATE DATA:
+{normalized_candidate}
+
+TASK:
+Score this candidate using the following weighted criteria:
+
+WEIGHTS:
+- Skill Match (35%): How well do their primary/secondary skills match JD required skills?
+- Experience Match (25%): Does their experience level match the JD minimum?
+- Role Relevance (20%): Is their normalized title and domain relevant to the JD?
+- Cloud/Infra Fit (10%): Do they have cloud, DevOps, or infra skills mentioned in JD?
+- Notice Period Fit (10%): Is their notice period suitable? (< 30 days = 10, < 60 = 7, < 90 = 5, > 90 = 2)
+
+RULES:
+- Score each dimension 0–100.
+- Compute final_score as weighted average.
+- decision: "pass" if final_score >= 60, else "reject".
+- Output ONLY valid JSON. No explanation.
+
+OUTPUT JSON:
+{{
+  "candidate_id": "",
+  "scores": {{
+    "skill_match": 0,
+    "experience_match": 0,
+    "role_relevance": 0,
+    "infra_fit": 0,
+    "notice_fit": 0
+  }},
+  "final_score": 0,
+  "decision": "pass"
+}}
+"""
+
+STAGE4_DEEP_REVIEW_PROMPT = """
+You are a senior hiring evaluator at a top tech company. You receive only the strongest pre-screened candidates.
+
+JOB DESCRIPTION:
+{jd}
+
+CANDIDATE FULL DATA:
+{candidate_data}
+
+RERANK SCORE: {score}/100
+
+TASK:
+Perform a deep, nuanced evaluation. Identify hidden strengths, practical fit signals, risks, and make a clear hiring recommendation.
+
+RULES:
+- Use only the data provided. No hallucinations.
+- Be decisive. Avoid vague language.
+- hidden_signal: any non-obvious positive or negative signal (company pedigree, project quality, progression speed, etc.)
+- confidence: 0.0 to 1.0
+
+OUTPUT JSON:
+{{
+  "verdict": "strong hire | hire | consider | reject",
+  "why": "one clear sentence explaining the verdict",
+  "strengths": ["strength 1", "strength 2"],
+  "risks": ["risk 1", "risk 2"],
+  "hidden_signal": "any non-obvious insight",
+  "confidence": 0.0
+}}
+"""
+
+STAGE5_FINAL_SELECTION_PROMPT = """
+You are the final hiring decision officer. You have all LLM deep reviews for the top 5 candidates.
+
+ALL TOP CANDIDATE REVIEWS:
+{all_top_5_results}
+
+TASK:
+Synthesize all reviews and produce the final ranked shortlist. Consider:
+- Verdict strength (strong hire > hire > consider > reject)
+- Confidence scores
+- Risk levels
+- Overall fit signals
+
+OUTPUT ONLY valid JSON:
+{{
+  "final_ranking": [
+    {{
+      "rank": 1,
+      "candidate_id": "",
+      "name": "",
+      "decision": "strong hire | hire | consider | reject",
+      "reason": "one concise sentence"
+    }}
+  ]
+}}
+"""

app/services/evaluation_service.py

@@ -0,0 +1,233 @@
+import asyncio
+import json
+import re
+import logging
+from typing import List, Dict, Any, Callable, Optional
+
+from app.utils.groq_client import get_groq_completion
+from app.models.schemas import (
+    Candidate, NormalizedCandidate, RerankResult,
+    DeepReview, FinalShortlist, FinalRank, EvaluationResponse,
+)
+from app.services.matching_service import match_service
+from app.prompts.templates import (
+    STAGE1_NORMALIZATION_PROMPT,
+    STAGE3_RERANK_PROMPT,
+    STAGE4_DEEP_REVIEW_PROMPT,
+    STAGE5_FINAL_SELECTION_PROMPT,
+)
+
+logger = logging.getLogger(__name__)
+
+# Concurrency throttle — max 3 parallel Groq calls
+sem = asyncio.Semaphore(3)
+
+
+async def _llm(messages: list) -> str:
+    async with sem:
+        return await get_groq_completion(messages)
+
+
+def _parse_json(raw: str) -> dict:
+    """Extract first JSON object from LLM response."""
+    match = re.search(r'\{.*\}', raw, re.DOTALL)
+    if match:
+        return json.loads(match.group())
+    return json.loads(raw)
+
+
+# ────────────────────────────────────────────────
+# Stage 1 — Normalize
+# ────────────────────────────────────────────────
+async def normalize_candidate(jd: str, candidate: Candidate) -> NormalizedCandidate:
+    candidate_raw = candidate.model_dump_json()
+    prompt = STAGE1_NORMALIZATION_PROMPT.format(
+        jd=jd,
+        candidate_raw=candidate_raw,
+        candidate_id=candidate.id,
+    )
+    resp = await _llm([
+        {"role": "system", "content": "You are a professional data normalizer. Output JSON ONLY. No markdown."},
+        {"role": "user", "content": prompt},
+    ])
+    try:
+        data = _parse_json(resp)
+        data["candidate_id"] = candidate.id  # Ensure ID is always correct
+        return NormalizedCandidate(**data)
+    except Exception as e:
+        logger.warning(f"[Stage1] Failed to normalize {candidate.name}: {e}")
+        return NormalizedCandidate(
+            candidate_id=candidate.id,
+            name=candidate.name,
+            normalized_title="Unknown",
+            experience_years=0,
+            primary_skills=[],
+            secondary_skills=[],
+            backend_score=0,
+            frontend_score=0,
+            cloud_score=0,
+            database_score=0,
+            notice_period_days=90,
+            location="Unknown",
+            employment_status="Unknown",
+            salary_expectation="Unknown",
+            flags=["Normalization Error"],
+        )
+
+
+# ────────────────────────────────────────────────
+# Stage 3 — Rerank
+# ────────────────────────────────────────────────
+async def rerank_candidate(jd: str, normalized: NormalizedCandidate) -> RerankResult:
+    resp = await _llm([
+        {"role": "system", "content": "You are a recruitment scoring engine. Output JSON ONLY. No markdown."},
+        {"role": "user", "content": STAGE3_RERANK_PROMPT.format(
+            jd=jd,
+            normalized_candidate=normalized.model_dump_json(),
+        )},
+    ])
+    try:
+        data = _parse_json(resp)
+        data["candidate_id"] = normalized.candidate_id
+        return RerankResult(**data)
+    except Exception as e:
+        logger.warning(f"[Stage3] Rerank failed for {normalized.candidate_id}: {e}")
+        return RerankResult(
+            candidate_id=normalized.candidate_id,
+            scores={},
+            final_score=0,
+            decision="reject",
+        )
+
+
+# ────────────────────────────────────────────────
+# Stage 4 — Deep Review
+# ────────────────────────────────────────────────
+async def review_candidate(
+    jd: str, candidate: Candidate, score: float
+) -> DeepReview:
+    resp = await _llm([
+        {"role": "system", "content": "You are a senior hiring evaluator. Output JSON ONLY. No markdown."},
+        {"role": "user", "content": STAGE4_DEEP_REVIEW_PROMPT.format(
+            jd=jd,
+            candidate_data=candidate.model_dump_json(),
+            score=round(score, 1),
+        )},
+    ])
+    try:
+        data = _parse_json(resp)
+        data["candidate_id"] = candidate.id
+        return DeepReview(**data)
+    except Exception as e:
+        logger.warning(f"[Stage4] Deep review failed for {candidate.id}: {e}")
+        return DeepReview(
+            candidate_id=candidate.id,
+            verdict="reject",
+            why="Evaluation error — could not parse LLM response.",
+            strengths=[],
+            risks=["Evaluation error"],
+            hidden_signal="",
+            confidence=0.0,
+        )
+
+
+# ────────────────────────────────────────────────
+# Main Pipeline
+# ────────────────────────────────────────────────
+async def perform_hybrid_evaluation(
+    jd: str,
+    candidates: List[Candidate],
+    progress_cb: Optional[Callable[[str], None]] = None,
+) -> EvaluationResponse:
+    """
+    Full 5-stage hybrid evaluation pipeline.
+    progress_cb: optional callable for streaming progress logs to UI.
+    """
+
+    def log(msg: str):
+        logger.info(msg)
+        if progress_cb:
+            progress_cb(msg)
+
+    candidate_map = {c.id: c for c in candidates}
+
+    # ── Stage 1: Normalize all candidates ──────────────────────
+    log(f"[Stage 1] Normalizing {len(candidates)} candidates...")
+    norm_tasks = [normalize_candidate(jd, c) for c in candidates]
+    normalized_list: List[NormalizedCandidate] = await asyncio.gather(*norm_tasks)
+    normalized_map = {n.candidate_id: n for n in normalized_list}
+    log(f"[Stage 1] ✓ Normalization complete.")
+
+    # ── Stage 2: Embedding matching → Top 20 ───────────────────
+    log(f"[Stage 2] Running embedding match against Pinecone...")
+    try:
+        top_20 = await match_service.get_top_candidates(jd, candidates)
+    except Exception as e:
+        log(f"[Stage 2] ⚠ Pinecone unavailable ({e}). Falling back to all candidates.")
+        top_20 = candidates[:20]
+
+    # Clamp to available
+    top_20 = top_20[:20]
+    log(f"[Stage 2] ✓ Retrieved {len(top_20)} candidates.")
+
+    # ── Stage 3: Deterministic rerank → Top 10 ─────────────────
+    log(f"[Stage 3] Reranking {len(top_20)} candidates...")
+    rerank_tasks = [
+        rerank_candidate(jd, normalized_map[c.id])
+        for c in top_20
+        if c.id in normalized_map
+    ]
+    rerank_results: List[RerankResult] = await asyncio.gather(*rerank_tasks)
+    rerank_results.sort(key=lambda x: x.final_score, reverse=True)
+    top_10 = rerank_results[:10]
+    log(f"[Stage 3] ✓ Top 10 selected. Scores: {[round(r.final_score, 1) for r in top_10]}")
+
+    # ── Stage 4: LLM deep review → Top 5 ──────────────────────
+    top_5_results = top_10[:5]
+    log(f"[Stage 4] Deep reviewing top {len(top_5_results)} candidates...")
+    review_tasks = [
+        review_candidate(jd, candidate_map[r.candidate_id], r.final_score)
+        for r in top_5_results
+        if r.candidate_id in candidate_map
+    ]
+    reviews: List[DeepReview] = await asyncio.gather(*review_tasks)
+    review_map = {rev.candidate_id: rev for rev in reviews}
+    log(f"[Stage 4] ✓ Deep reviews complete.")
+
+    # ── Stage 5: Final synthesis ───────────────────────────────
+    log(f"[Stage 5] Synthesizing final shortlist...")
+    reviews_json = json.dumps([r.model_dump() for r in reviews])
+    final_resp = await _llm([
+        {"role": "system", "content": "You are the final hiring decision officer. Output JSON ONLY. No markdown."},
+        {"role": "user", "content": STAGE5_FINAL_SELECTION_PROMPT.format(
+            all_top_5_results=reviews_json
+        )},
+    ])
+
+    try:
+        final_data = _parse_json(final_resp)
+        shortlist = FinalShortlist(**final_data)
+    except Exception as e:
+        log(f"[Stage 5] ⚠ Synthesis parse failed ({e}). Using automatic ranking.")
+        shortlist = FinalShortlist(
+            final_ranking=[
+                FinalRank(
+                    rank=i + 1,
+                    candidate_id=r.candidate_id,
+                    name=candidate_map.get(r.candidate_id, Candidate(id=r.candidate_id, name="Unknown")).name,
+                    decision=review_map.get(r.candidate_id, DeepReview(
+                        candidate_id=r.candidate_id, verdict="consider", why="", strengths=[],
+                        risks=[], hidden_signal="", confidence=0
+                    )).verdict,
+                    reason="Auto-ranked by rerank score.",
+                )
+                for i, r in enumerate(top_5_results)
+            ]
+        )
+
+    log(f"[Stage 5] ✓ Pipeline complete. {len(shortlist.final_ranking)} candidates shortlisted.")
+
+    return EvaluationResponse(
+        shortlist=shortlist.final_ranking,
+        details={rev.candidate_id: rev.model_dump() for rev in reviews},
+    )

app/services/matching_service.py

@@ -0,0 +1,136 @@
+import os
+import asyncio
+import logging
+from typing import List, Tuple
+
+from app.models.schemas import Candidate
+
+logger = logging.getLogger(__name__)
+
+
+class MatchService:
+    """
+    Stage 2: Embedding-based semantic matching using Pinecone + SentenceTransformers.
+    Stores candidate embeddings, queries with JD embedding, returns top-K candidates.
+    """
+
+    def __init__(self):
+        self._model = None
+        self._index = None
+        self._initialized = False
+
+    def _lazy_init(self):
+        """Defer heavy imports until first use to keep startup fast."""
+        if self._initialized:
+            return
+
+        try:
+            from pinecone import Pinecone
+            from sentence_transformers import SentenceTransformer
+
+            api_key = os.getenv("PINECONE_API_KEY", "")
+            index_name = os.getenv("PINECONE_INDEX", "recruitment-index")
+            model_name = os.getenv("EMBEDDING_MODEL", "BAAI/bge-m3")
+
+            if not api_key:
+                raise ValueError("PINECONE_API_KEY not set in environment.")
+
+            logger.info(f"[MatchService] Connecting to Pinecone index: {index_name}")
+            pc = Pinecone(api_key=api_key)
+            self._index = pc.Index(index_name)
+
+            logger.info(f"[MatchService] Loading embedding model: {model_name}")
+            self._model = SentenceTransformer(model_name)
+
+            self._initialized = True
+            logger.info("[MatchService] Ready.")
+
+        except Exception as e:
+            logger.error(f"[MatchService] Initialization failed: {e}")
+            raise
+
+    def get_embedding(self, text: str) -> List[float]:
+        self._lazy_init()
+        return self._model.encode(text, normalize_embeddings=True).tolist()
+
+    def _build_search_text(self, c: Candidate) -> str:
+        parts = [
+            c.name or "",
+            c.skills or "",
+            c.experience or "",
+            c.projects or "",
+            c.education or "",
+            c.resume_text or "",
+        ]
+        return " ".join(p for p in parts if p.strip())
+
+    async def get_top_candidates(
+        self, jd: str, candidates: List[Candidate], top_k: int = None
+    ) -> List[Candidate]:
+        """
+        1. Embed all candidates and upsert to Pinecone.
+        2. Embed JD and query Pinecone.
+        3. Return top_k candidates sorted by similarity.
+        """
+        if top_k is None:
+            top_k = int(os.getenv("STAGE2_TOP_K", "20"))
+
+        self._lazy_init()
+        candidate_map = {c.id: c for c in candidates}
+
+        # Build and embed vectors (run in thread to avoid blocking event loop)
+        loop = asyncio.get_event_loop()
+
+        def build_vectors():
+            vectors = []
+            for c in candidates:
+                text = self._build_search_text(c)
+                embedding = self.get_embedding(text)
+                vectors.append({
+                    "id": c.id,
+                    "values": embedding,
+                    "metadata": {
+                        "name": c.name,
+                        "email": c.email or "",
+                    },
+                })
+            return vectors
+
+        logger.info(f"[MatchService] Embedding {len(candidates)} candidates...")
+        vectors = await loop.run_in_executor(None, build_vectors)
+
+        # Upsert in batches of 100 (Pinecone limit)
+        batch_size = 100
+        for i in range(0, len(vectors), batch_size):
+            batch = vectors[i: i + batch_size]
+            self._index.upsert(vectors=batch)
+
+        # Embed JD and query
+        logger.info("[MatchService] Querying Pinecone with JD embedding...")
+        jd_embedding = await loop.run_in_executor(None, self.get_embedding, jd)
+
+        effective_k = min(top_k, len(candidates))
+        query_results = self._index.query(
+            vector=jd_embedding,
+            top_k=effective_k,
+            include_metadata=True,
+        )
+
+        top_candidates: List[Candidate] = []
+        for match in query_results.matches:
+            if match.id in candidate_map:
+                top_candidates.append(candidate_map[match.id])
+
+        logger.info(f"[MatchService] Retrieved {len(top_candidates)} top candidates.")
+        return top_candidates
+
+    async def cleanup_index(self, candidate_ids: List[str]):
+        """Optional: remove candidate vectors after evaluation to keep index clean."""
+        try:
+            self._index.delete(ids=candidate_ids)
+            logger.info(f"[MatchService] Cleaned up {len(candidate_ids)} vectors from index.")
+        except Exception as e:
+            logger.warning(f"[MatchService] Cleanup failed: {e}")
+
+
+match_service = MatchService()

app/utils/groq_client.py

@@ -0,0 +1,37 @@
+import os
+import logging
+from groq import AsyncGroq
+from app.utils.key_manager import key_manager
+
+logger = logging.getLogger(__name__)
+
+
+async def get_groq_completion(messages: list, model: str = None) -> str:
+    """
+    Calls Groq API with automatic key rotation on failure.
+    Retries across all available keys before raising.
+    """
+    if model is None:
+        model = os.getenv("GROQ_MODEL", "llama3-70b-8192")
+
+    max_retries = max(key_manager.key_count(), 1)
+    last_error = None
+
+    for attempt in range(max_retries):
+        try:
+            api_key = key_manager.get_next_key()
+            client = AsyncGroq(api_key=api_key)
+            response = await client.chat.completions.create(
+                messages=messages,
+                model=model,
+                temperature=0.2,          # Low temp for deterministic structured output
+                max_tokens=2048,
+            )
+            return response.choices[0].message.content
+
+        except Exception as e:
+            logger.warning(f"[Groq] Attempt {attempt + 1}/{max_retries} failed: {e}")
+            last_error = e
+            continue
+
+    raise Exception(f"[Groq] All API keys exhausted. Last error: {last_error}")

app/utils/key_manager.py

@@ -0,0 +1,32 @@
+import os
+import threading
+from typing import List
+
+
+class KeyRotationManager:
+    def __init__(self):
+        keys_str = os.getenv("GROQ_API_KEYS", "")
+        if not keys_str:
+            keys_str = os.getenv("GROQ_API_KEY", "")
+
+        self.keys = [k.strip() for k in keys_str.split(",") if k.strip()]
+        print(f"[KeyManager] Initialized with {len(self.keys)} key(s).")
+        if not self.keys:
+            print("[KeyManager] WARNING: No GROQ_API_KEYS or GROQ_API_KEY found in environment!")
+
+        self.current_index = 0
+        self.lock = threading.Lock()
+
+    def get_next_key(self) -> str:
+        with self.lock:
+            if not self.keys:
+                raise ValueError("No GROQ API keys found. Set GROQ_API_KEYS or GROQ_API_KEY in your .env file.")
+            key = self.keys[self.current_index]
+            self.current_index = (self.current_index + 1) % len(self.keys)
+            return key
+
+    def key_count(self) -> int:
+        return len(self.keys)
+
+
+key_manager = KeyRotationManager()

requirements.txt

@@ -0,0 +1,12 @@
+fastapi==0.115.0
+uvicorn==0.30.6
+groq==0.11.0
+pinecone==5.0.1
+sentence-transformers==3.1.1
+pandas==2.2.3
+pydantic==2.9.2
+python-dotenv==1.0.1
+gradio==4.44.0
+httpx==0.27.2
+python-multipart==0.0.12
+aiofiles==24.1.0