🤖 Agentic Resume Ranking System

An automation-based resume ranking system that scores candidate resumes against a job description using a simple greedy keyword-matching algorithm and an n8n workflow.

The system accepts a job description and multiple resumes, cleans and tokenizes the text, calculates match scores, ranks the candidates, saves the top results to CSV, and can send the top candidates through an email automation node.

---

📌 Project Overview

Hiring teams often receive multiple resumes for one job opening. Manually checking every resume against the job description takes time, especially when the first screening is mostly based on keyword matching.

This project builds a lightweight resume screening workflow using:

• Python for text preprocessing and greedy scoring
• n8n for workflow automation
• Webhook input for receiving job description and resume data
• CSV output for storing ranked candidates
• Email node for sending top candidate results

This is an academic automation/AI assignment project, but it is structured like a small real-world HR automation prototype.

---

🎯 Objective

The objective of this project is to automatically rank resumes based on how closely they match a given job description.

The system:

1. Accepts a job description.
2. Accepts multiple candidate resumes.
3. Cleans and tokenizes the text.
4. Calculates a greedy keyword match score.
5. Sorts resumes from highest to lowest score.
6. Returns the top candidates.
7. Saves ranked output to a CSV file.
8. Sends the result through an automated workflow.

---

🧠 What Makes It “Agentic”?

The system behaves like a small automation agent because it performs multiple connected steps without manual ranking:

Receive input → Process resumes → Score candidates → Rank candidates → Save results → Send results

Instead of only running a standalone script, the project connects the scoring logic inside an n8n workflow so the process can be triggered through a webhook and continued automatically.

---

✨ Features

• Accepts job description and multiple resumes.
• Cleans text by lowercasing and removing non-alphabetic characters.
• Tokenizes job description and resume content.
• Calculates greedy keyword match percentage.
• Sorts candidates by highest score.
• Returns top 3 candidates.
• Saves top candidates to CSV.
• Includes n8n workflow JSON.
• Includes standalone Python demo for local testing.
• Beginner-friendly code structure and comments.

---

🛠️ Tech Stack

Category	Technology
Automation Tool	n8n
Programming Language	Python
Algorithm	Greedy Keyword Matching
Input Method	Webhook / JSON Payload
Output Format	CSV
Testing Tool	Postman or cURL
Data Format	JSON, CSV

---

📁 Repository Structure

Agentic-Resume-Ranking-System/
│
├── src/
│   ├── local_demo.py
│   ├── n8n_python_node.py
│   ├── greedy_algorithm.py
│   └── preprocessing.py
│
├── workflow/
│   └── resume_ranking_agent.n8n.json
│
├── sample_data/
│   └── sample_payload.json
│
├── outputs/
│   └── top_candidates.csv
│
├── docs/
│   ├── assignment_brief.docx
│   └── code_quality_notes.md
│
├── requirements.txt
├── .gitignore
└── README.md

---

⚙️ How the Algorithm Works

The algorithm follows a simple greedy keyword-matching approach.

Step 1: Clean Text

The job description and resumes are converted to lowercase. Punctuation, numbers, and special characters are removed.

Example:

"Python, Machine Learning!"

becomes:

python machine learning

Step 2: Tokenize Text

The cleaned text is split into individual words.

["python", "machine", "learning"]

Step 3: Count Matches

Each resume word is checked against the job description tokens. If the word exists in the job description, it is counted as a match.

Step 4: Calculate Score

score = (matched_words / total_job_description_words) * 100

Step 5: Rank Candidates

Candidates are sorted by score in descending order, and the top 3 candidates are returned.

---

🔁 Workflow Architecture

flowchart LR
    A[Webhook Input] --> B[Python Code Node]
    B --> C[Clean and Tokenize Text]
    C --> D[Greedy Match Scoring]
    D --> E[Sort Top Candidates]
    E --> F[Save CSV Output]
    F --> G[Send Email Result]

Loading

---

🚀 How to Run Locally

The local demo can be tested without n8n.

1. Clone the Repository

git clone https://github.com/fayzliaqat/Agentic-Resume-Ranking-System.git
cd Agentic-Resume-Ranking-System

2. Run the Local Demo

python src/local_demo.py

3. Expected Output

Top candidates:
Ali - 100%
Sara - 90%
Javed - 0%

CSV saved at: outputs/top_candidates.csv

---

📤 Sample Input Payload

The n8n webhook expects a JSON payload like this:

{
  "job_description": "We are hiring an AI Engineer skilled in Python, Machine Learning, and Data Analysis.",
  "resumes": [
    {
      "name": "Ali",
      "text": "AI engineer with strong Python, TensorFlow, and deep learning expertise."
    },
    {
      "name": "Sara",
      "text": "Data scientist specialized in Python, machine learning, and predictive analytics."
    },
    {
      "name": "Javed",
      "text": "Chef with experience in continental cuisine."
    }
  ]
}

---

📥 Sample Output

The output CSV contains the top candidates and their scores.

name,score
Ali,100
Sara,90
Javed,0

---

🔌 How to Use the n8n Workflow

1. Install or Open n8n

You can run n8n locally or use n8n cloud.

Local installation example:

npx n8n

n8n usually opens at:

http://localhost:5678

---

2. Import Workflow

1. Open n8n.
2. Go to Workflows.
3. Select Import from File.
4. Import:

workflow/resume_ranking_agent.n8n.json

---

3. Configure Email Node

The workflow includes an email node, but credentials are intentionally removed from the public version.

Before running the workflow:

1. Open the email node.
2. Add your SMTP credentials.
3. Set sender and receiver email addresses.
4. Save the workflow.

---

4. Test Webhook

Use Postman or cURL to send a POST request.

Example:

curl -X POST http://localhost:5678/webhook-test/resume-ranking \
  -H "Content-Type: application/json" \
  -d @sample_data/sample_payload.json

---

🧪 Important Files Explained

File	Purpose
src/local_demo.py	Standalone Python script for testing the ranking logic locally
src/n8n_python_node.py	Python code designed for the n8n Code node
src/greedy_algorithm.py	Simple example of greedy matching algorithm
src/preprocessing.py	Demonstrates text cleaning and tokenization
workflow/resume_ranking_agent.n8n.json	Importable n8n workflow
sample_data/sample_payload.json	Sample input payload for testing
outputs/top_candidates.csv	Example output file
docs/code_quality_notes.md	Notes about code quality and comments

---

✅ Current Status

This project is complete as an academic prototype. The greedy matching algorithm, preprocessing logic, sample data, n8n workflow, and output CSV are included.

---

⚠️ Limitations

• This system uses keyword matching, not semantic similarity.
• It does not understand synonyms.
• It does not deeply understand candidate experience.
• Repeated matching words can increase the score.
• PDF parsing is not fully implemented in the local script.
• The ranking is useful for simple screening, not final hiring decisions.
• Email and Google Sheets credentials must be configured manually in n8n.

---

🔮 Future Improvements

• Add PDF resume parsing.
• Add semantic similarity using embeddings.
• Add stopword removal.
• Add skill weighting.
• Add experience-based scoring.
• Add Streamlit dashboard for HR users.
• Add Google Sheets integration.
• Add better candidate report generation.
• Add duplicate word handling.
• Add support for DOCX resumes.
• Add confidence explanations for each candidate score.

---

🧾 GitHub Safety Note

The public workflow file does not include private credentials. Email addresses, credential IDs, and local machine paths should always be removed before pushing an n8n workflow to GitHub.

---

👨‍💻 Author

Fayz Liaqat
Artificial Intelligence Student