TalentMatch

An AI-powered recruitment matching platform that ranks candidates' resumes against job postings using Vector Similarity Search (FAISS) and a trained XGBoost Machine Learning Classifier.

---

🏗️ System Architecture

The TalentMatch system connects a modern Vite-React frontend with a FastAPI backend server. It relies on a high-speed vector search index for candidate matching, backed by a Neon PostgreSQL cloud database for metadata persistence.

graph TD
    subgraph Client [React Frontend - Port 5173]
        UI[Interactive Dashboard UI]
    end

    subgraph Server [FastAPI Server - Port 8000]
        API[API Router /rank-candidates]
    end

    subgraph Database [Neon Cloud Database]
        PG[(PostgreSQL Tables)]
    end

    subgraph ML [Machine Learning & Embeddings]
        ST[SentenceTransformer model]
        FI[FAISS Vector Index]
        XG[Trained XGBoost Classifier]
    end

    UI -->|1. Select Title & Search| API
    API -->|2. Query Job Details| PG
    API -->|3. Embed Title + Description| ST
    API -->|4. Search K-Nearest Resumes| FI
    API -->|5. Fetch Candidate Resumes| PG
    API -->|6. Compile Features & Run Inference| XG
    API -->|7. Return Ranked Candidates| UI

Loading

---

🔄 Data Pipeline Flow

The platform operates through a structured multi-stage data pipeline:

Phase 1: Data Cleaning & Setup (process_data.py)

1. Resume Cleaning: Raw resumes (Resume.csv) are trimmed to keep resume_id, resume_text, and category, filtering out missing entries.
2. Job Postings Filtering: Raw postings (postings.csv) are filtered down to tech-relevant roles (containing keywords like Software, Engineer, Developer, Data, Analyst), sampled to 5,000 items, and aggregated with job skills.
3. Database Ingestion:
   • db/setup_db.py creates candidates and jobs tables in your Neon PostgreSQL database.
   • db/seed.py seeds all 2,484 clean resumes and 5,000 clean jobs into PostgreSQL.

Phase 2: Vector Indexing

1. Embed Resumes: embeddings/embed_resumes.py converts all resume texts into dense 384-dimensional vectors using the all-MiniLM-L6-v2 SentenceTransformer model, saving the vectors in a NumPy file (resume_embeddings.npy).
2. FAISS Indexing: embeddings/faiss_index.py normalizes these vectors to fit a cosine similarity space and builds a Flat Inner Product index (resume_faiss.index) for high-speed nearest-neighbor retrieval.

Phase 3: Machine Learning Training (ml/)

1. Pairs Creation: ml/create_training_pairs.py generates a balanced dataset of 30,000 matches and non-matches by mapping job titles to relevant/unrelated resume categories.
2. Feature Extraction: ml/build_features.py compiles feature matrices from these pairs (embedding distance, keyword overlap, etc.).
3. XGBoost Training: ml/train_model.py trains an XGBoost classifier, outputs precision/recall scores, and serializes the model to models/ranking_model.pkl.

---

🧠 How It Predicts

Rather than relying on a hardcoded formula, TalentMatch uses a trained XGBoost Classifier to evaluate candidate suitability.

When a user triggers a candidate search, the backend extracts four distinct features for each retrieved candidate:

1. Cosine Similarity (Weight: 0.3377): The semantic vector distance between the job posting (title + description) and the candidate's resume text, calculated using all-MiniLM-L6-v2 embeddings.
2. Title Keyword Match Ratio (Weight: 0.2675): The percentage of keywords in the job title that directly appear in the candidate's resume text.
3. Resume Character Length (Weight: 0.2389): The length of the candidate's resume text (helps evaluate resume completeness).
4. Skill Overlap Ratio (Weight: 0.1558): The fraction of the job's required skill abbreviations (e.g. IT, ENG, MGMT) found in the candidate's resume.

The model evaluates these features for the top candidate matches retrieved by FAISS and predicts the probability that the candidate is a match (0.0 to 1.0). Candidates are returned sorted by this predicted probability (final_score).

📊 Model Evaluation Metrics

Below are the performance metrics of the trained XGBoost classifier evaluated on the test split:

Metric	Value / Ratio	Definition / Context
Accuracy	65.20%	Total ratio of correctly predicted matches and non-matches.
Precision (Match)	0.65	Out of all candidates labeled as a match by the model, how many were true matches.
Recall (Match)	0.65	Out of all true matches, how many the model successfully detected.
F1-Score (Match)	0.65	Balanced harmonic mean of Precision and Recall.

---

📡 API Reference & Sample Queries

1. Get Distinct Job Titles

Retrieves the list of unique job titles to populate dropdown menus on the UI.

• Endpoint: GET /job-titles
• Response Sample:

{
  "titles": [
    "  Data Architect",
    " AVP Underwriter ",
    " Cyber Security Analyst 1 - Remote US",
    " Software Engineer",
    " Lead Semiconductor Engineer"
  ]
}

2. Rank Candidates

Retrieves top candidate matches for a specific job title.

• Endpoint: POST /rank-candidates
• Content-Type: application/json
• Request Body:

{
  "title": "Software Engineer",
  "description": "Looking for a Software Engineer with Python and machine learning experience.",
  "top_k": 5
}

• Response Sample:

{
  "job_title": "Software Engineer",
  "results": [
    {
      "resume_id": 62994611,
      "category": "AGRICULTURE",
      "similarity": 0.5233,
      "skill_overlap": 1.0,
      "final_score": 0.9213
    },
    {
      "resume_id": 61579998,
      "category": "ENGINEERING",
      "similarity": 0.5421,
      "skill_overlap": 1.0,
      "final_score": 0.9057
    },
    {
      "resume_id": 36434348,
      "category": "INFORMATION-TECHNOLOGY",
      "similarity": 0.4969,
      "skill_overlap": 0.5,
      "final_score": 0.8905
    }
  ]
}

---

🚀 Quick Start Guide

Prerequisites

• Python 3.10+
• Node.js & npm

1. Configuration (.env)

Create a .env file at the root of the project and add your Neon PostgreSQL connection string:

DATABASE_URL=postgresql://user:password@host/dbname?sslmode=require

2. Backend Installation & Run

1. Install Python packages:

   pip install pandas numpy sentence-transformers faiss-cpu psycopg2-binary sqlalchemy python-dotenv xgboost scikit-learn joblib fastapi uvicorn

2. Prep and Clean Data:

   python process_data.py

3. Set up and Seed Database Tables:

   python db/setup_db.py
   python db/seed.py

4. Build Embeddings & Search Index:

   python embeddings/embed_resumes.py
   python embeddings/embed_jobs.py
   python embeddings/faiss_index.py

5. Train Machine Learning Model:

   python ml/create_training_pairs.py
   python ml/build_features.py
   python ml/train_model.py

6. Start the API Server:

   python -m uvicorn api.main:app --port 8000

3. Frontend Installation & Run

In a new terminal window:

1. Navigate to the frontend directory:

   cd frontend

2. Install npm packages:

   npm install

3. Launch React:

   npm run dev

4. Open your browser and navigate to http://localhost:5173/.