AI_Resume_Scanner

🚀 MATCH.AI — AI Resume Screener & Feedback System

Project 1 — AI & Generative AI Fellowship Program @ Zeppelin Lab

An enterprise-grade, deterministic AI Resume Screener & Structured Feedback System built for high-accuracy recruitment screening. Powered by Google Gemini Flash, strictly typed with Pydantic, served via FastAPI, and styled with a 3D Glassmorphism Executive Studio Dashboard.

---

📋 Project Overview

MATCH.AI is an AI-powered resume screening system that:

• Accepts candidate resumes (PDF, DOCX, TXT) and job descriptions
• Uses Google Gemini Flash AI to perform structured, deterministic evaluations
• Returns validated JSON assessments with match scores, matched/missing requirements, and actionable suggestions
• Includes an Evidence Grounding Verifier to prevent AI hallucinations
• Features a premium 3D interactive web dashboard with dark/light themes

---

🛠️ Tech Stack

---

✨ Features & Architecture

graph LR
    A[Candidate Resume PDF / DOCX / TXT] --> C[FastAPI Scanner /api/scan]
    B[Job Description Spec] --> C
    C --> D[PDF / DOCX / TXT Extractor Engine]
    D --> E[Gemini Flash temperature=0.0]
    E --> F[Pydantic Schema Validation]
    F --> G[Evidence Grounding Verifier]
    G --> H[3D Interactive Studio Dashboard]

1. Deterministic AI Scoring Engine (temperature = 0.0): Evaluates candidates against job descriptions without LLM hallucinations or variance.
2. Strict Pydantic Output Validation: Enforces valid JSON structure (Assessment schema) with scores (0–100), rationale, matched requirements, skill gaps, and suggestions.
3. Evidence Grounding Verifier: Token-based semantic overlap analysis to verify every AI claim against actual resume text.
4. 3D Glassmorphism Executive Dashboard: Dual Aurora Light & Obsidian Dark Themes, 3D particle canvas, perspective mouse tilt effects.
5. Multi-Format Document Support: Supports .pdf, .docx, .doc, and .txt files.

---

🚀 Setup Steps

Prerequisites

• Python 3.10 or higher
• Git
• A Google Gemini API Key (Get one free)

1. Clone the Repository

git clone https://github.com/majidali1256/ai-resume-screener.git
cd ai-resume-screener

2. Create Virtual Environment & Install Dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Configure Environment Variables

cp .env.example .env
# Edit .env and add your Gemini API Key:
# GEMINI_API_KEY=your_api_key_here
# AI_MODEL=gemini-2.0-flash

⚠️ Security Note: .env is excluded from version control via .gitignore. Never commit API keys.

4. Run the Server

uvicorn main:app --host 0.0.0.0 --port 8000

Open http://localhost:8000 to launch the 3D Executive Studio Dashboard!

5. Run Tests

pytest tests/

---

🔌 API Reference

POST /api/scan

Upload a candidate resume and job description to get a complete JSON assessment.

Request (Multipart Form Data):

• resume_file: .pdf, .docx, .doc, or .txt file
• jd_file (optional): Job Description file
• jd_text (optional): Raw job description text

Response Schema:

{
  "match_score": 85,
  "score_rationale": "Strong alignment across Python, FastAPI, and React...",
  "matched_requirements": ["5+ years Python experience", "FastAPI expertise"],
  "missing_requirements": ["GraphQL experience"],
  "suggestions": ["Quantify accomplishments with specific metrics"],
  "limitations": []
}

GET /api/health

Returns service health status.

GET /api/demo

Runs a sample scan using built-in benchmark data.

---

📁 Project Structure

ai-resume-screener/
├── main.py                    # FastAPI server entry point
├── app.py                     # Gradio interface (Hugging Face Spaces)
├── resume_scanner/
│   ├── assessor.py            # Gemini Flash AI assessment engine
│   ├── extractor.py           # PDF/DOCX/TXT text extraction
│   ├── grounding.py           # Evidence grounding verifier
│   └── models.py              # Pydantic Assessment schema
├── static/
│   └── index.html             # 3D Glassmorphism Executive Dashboard
├── data/
│   ├── benchmark/             # Golden evaluation benchmark library
│   └── uploads/               # Temporary upload storage (gitignored)
├── tests/
│   └── test_screener.py       # Automated pytest suite
├── .github/
│   └── workflows/ci.yml       # GitHub Actions CI pipeline
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Docker deployment config
├── .env.example               # Environment variable template
├── .gitignore                 # Security: excludes .env, uploads, caches
└── README.md                  # This file

---

🔒 Security & Privacy

• API keys are stored in .env (never committed — excluded by .gitignore)
• Uploaded resumes are processed in-memory and cleaned up immediately after scanning
• No PII storage: The system does not persist any candidate personal data

---

🌐 Live Deployment

---

👨‍💻 Team & Roles

Responsibilities:

• AI/LLM Engine Development (Gemini Flash integration, structured prompting)
• Backend Architecture (FastAPI REST API, Pydantic validation)
• Frontend Development (3D Glassmorphism Dashboard, Gradio interface)
• Evidence Grounding Verifier module
• Testing & CI/CD (Pytest suite, GitHub Actions)
• Deployment (Hugging Face Spaces, Docker)

---

📄 License

This project is licensed under the MIT License.