Skip to content

Fa-Abdullah/HR-AI-Assistant

BranchesTags

Repository files navigation

HR AI Assistant

An intelligent Human Resources Assistant built with Django that automates the recruitment workflow—from CV upload and candidate analysis to job matching and hiring pipeline management.

Unlike many HR systems that rely on external AI APIs or Large Language Models (LLMs), this project implements a custom rule-based AI engine for CV parsing, position inference, and candidate-job matching. This approach provides full transparency, fast execution, offline capability, and complete control over the scoring logic.

Overview

Recruitment teams often spend a significant amount of time manually reviewing CVs, comparing applicants against job requirements, and tracking hiring progress.

The HR AI Assistant automates these repetitive tasks by:

  • Extracting candidate information directly from uploaded CVs.
  • Inferring the candidate's actual job role based on work experience.
  • Matching candidates with available job postings using a weighted scoring algorithm.
  • Tracking applicants throughout the hiring pipeline.
  • Simplifying candidate communication through WhatsApp and Email integration.
  • Managing employee records through an intuitive web dashboard.

Key Features

Automated CV Parsing

Upload a CV in PDF or DOCX format and the system automatically extracts:

  • Full Name
  • Email Address
  • Phone Number
  • Skills
  • Education History
  • Years of Experience
  • Current / Previous Position

No manual data entry is required.

Smart Position Inference

Many CVs never explicitly mention a job title.

Instead of relying only on written titles, the system analyzes the candidate's work responsibilities and achievements.

Examples:

  • "Developed REST APIs"
  • "Designed databases"
  • "Built machine learning models"
  • "Led a software development team"

These descriptions are semantically analyzed to infer the candidate's actual profession before normalizing it into a standardized role.

The inference engine includes:

  • Semantic role detection
  • Explicit title matching
  • Arabic & English role recognition
  • Seniority detection

Supported seniority levels:

  • Entry Level
  • Junior
  • Mid-Level
  • Senior
  • Lead

Intelligent Rule-Based Matching Engine

Instead of using GPT or external APIs, the project implements a transparent weighted scoring algorithm.

Each candidate receives a score between 0 and 100 based on:

Factor Weight
Position Alignment 40%
Skill Matching 40%
Years of Experience 20%

The final score is generated using deterministic rules, making every recommendation explainable.

Automatic Job Recommendation

The system automatically scans every available job posting.

For each candidate it:

  1. Calculates the match score.
  2. Compares all available jobs.
  3. Selects the highest-scoring position.
  4. Displays the detailed score breakdown.

Hiring Pipeline Management

Candidates move through predefined recruitment stages:

Initial Screening

↓

HR Interview

↓

Technical Interview

↓

Final Interview

↓

Offer

↓

Hired / Rejected

This allows recruiters to track candidate progress throughout the hiring process.

Candidate Communication

Recruiters can contact applicants directly from the dashboard using:

  • WhatsApp one-click link generation
  • Email integration

Employee Management

Manage employee information after hiring, including records and administrative data.

Responsive Dashboard

A clean and responsive user interface built using:

  • Bootstrap
  • HTML Templates
  • CSS

Designed for both desktop and mobile usage.

How the AI Works

Although called an "AI Assistant", the intelligence comes from a custom-built rule engine rather than a language model.

This makes the system:

  • Fast
  • Explainable
  • Offline-friendly
  • Easy to customize
  • Deterministic

CV Parsing Engine (utils/parser.py)

The parser performs several stages.

File Processing

Supported formats:

  • PDF
  • DOCX

Libraries used:

  • PyMuPDF
  • pdfplumber (fallback)
  • python-docx

Information Extraction

The parser extracts:

  • Candidate name
  • Email
  • Phone number
  • Education
  • Skills
  • Experience
  • Job Position

using:

  • Regular Expressions
  • Pattern Matching
  • Heuristics

Duplicate education entries are automatically removed.

Skill Extraction

Skills are identified using:

  • Curated technical skill dictionaries
  • Soft skill dictionaries
  • Regex patterns such as:
Skills:

or

Proficient in ...

The extracted skills are normalized before matching.

Position Inference

The position detector works in multiple stages.

1. Semantic Detection

The engine searches for responsibility patterns.

Example:

Recruitment

Employee Relations

Payroll

↓

HR Professional

Developed APIs

Backend Development

Database Design

↓

Software Engineer

Model Training

Deep Learning

Data Analysis

↓

Data Scientist

2. Explicit Title Matching

If no semantic match exists, the parser searches for direct job titles such as:

  • Software Engineer
  • Data Scientist
  • HR Specialist
  • Project Manager
  • CEO

Arabic equivalents are also supported.

3. Seniority Detection

The engine detects:

  • Junior
  • Mid
  • Senior
  • Lead
  • Entry Level

before combining them with the inferred role.

Example:

Senior Software Engineer

Lead Data Scientist

Junior HR Specialist

Matching Engine (utils/insights.py)

For every candidate-job pair, three independent scores are calculated.

Position Score (40%)

Checks:

  • Exact title match
  • Partial word overlap
  • Category similarity

Example:

Backend Engineer

Software Engineer

↓

Partial Match

Skill Score (40%)

Measures the overlap between:

Candidate Skills

and

Required Job Skills

using the percentage of matched skills.

Experience Score (20%)

Compares:

Candidate Years of Experience

vs

Minimum Required Experience

The score is capped at 100%.

Final Recommendation

Based on the total score:

Score Recommendation
80 – 100 Strong Match – Schedule Interview
60 – 79 Good Match – Consider for Interview
40 – 59 Moderate Match – Manual Review Required
Below 40 Weak Match

Technology Stack

Backend

  • Django
  • Python 3.x
  • Django REST Framework
  • PostgreSQL
  • python-dotenv
  • PyMuPDF
  • pdfplumber
  • python-docx

Frontend

  • Django Template Language
  • HTML
  • CSS
  • Bootstrap

Database

Production

  • PostgreSQL

Development

  • SQLite

Development Tools

  • Git
  • Docker
  • Docker Compose
  • venv

Project Structure

HR-AI-Assistant/
│
├── core/
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
│
├── enppi_backend/
│   ├── models.py
│   ├── views.py
│   ├── serializers.py
│   ├── admin.py
│   └── utils/
│       ├── parser.py
│       └── insights.py
│
├── templates/
├── media/
├── static/
├── .env
├── .env.example
├── manage.py
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── README.md

Important Files

manage.py

Command-line utility for running Django commands such as:

  • runserver
  • migrate
  • makemigrations
  • createsuperuser

.env

Stores sensitive configuration such as:

  • SECRET_KEY
  • DEBUG
  • Database credentials

This file should never be committed to Git.

requirements.txt

Contains every Python dependency required by the project.

Install them using:

pip install -r requirements.txt

core/

Contains the global Django configuration.

enppi_backend/

Contains the business logic including:

  • Models
  • Views
  • REST APIs
  • Matching Engine
  • CV Parser

templates/

Contains all HTML templates rendered by Django.

media/

Stores uploaded CVs and other user files.

REST API

Endpoint Method Description
/api/candidates/ GET List all candidates
/api/candidates/<id>/ GET Candidate details
/api/candidates/upload/ POST Upload & parse CV
/api/candidates/<id>/ PUT Update candidate
/api/candidates/<id>/ DELETE Delete candidate
/api/jobs/ GET / POST List or create jobs
/api/match/<candidate_id>/<job_id>/ GET Match a candidate with a job
/api/auto-match/<candidate_id>/ GET Automatically recommend the best job
/api/candidates/<id>/whatsapp/ POST Generate WhatsApp link
/api/candidates/<id>/email/ POST Send candidate email

Local Installation

Prerequisites

  • Python 3.x
  • pip
  • PostgreSQL

Installation

git clone <repository-url>

cd HR-AI-Assistant

python -m venv venv

# Windows
venv\Scripts\activate

# Linux / macOS
source venv/bin/activate

pip install -r requirements.txt

cp .env.example .env

python manage.py migrate

python manage.py createsuperuser

python manage.py runserver

Application URL:

http://127.0.0.1:8000

Running with Docker

docker-compose up --build

Why This Project?

Unlike many HR assistants that depend on external AI services, this project demonstrates how intelligent recruitment automation can be achieved using carefully designed rule-based algorithms.

Advantages include:

  • Explainable decision making
  • No API costs
  • Offline operation
  • Fast execution
  • Easy customization
  • Deterministic scoring
  • Transparent recommendations

Future Improvements

Potential future enhancements include:

  • Resume ranking using sentence embeddings
  • OCR support for scanned CVs
  • Interview scheduling
  • Analytics dashboard
  • Multi-language support
  • Authentication & role-based access control
  • Email templates
  • Advanced recruitment reports

Contributing

Contributions are welcome.

  1. Fork the repository.
  2. Create a feature branch.
  3. Commit your changes.
  4. Push to GitHub.
  5. Open a Pull Request.

Contact

For questions, suggestions, or support:

Email: tmatm2540@gmail.com

About

AI-powered HR assistant that analyzes resumes, matches candidates to job descriptions, and streamlines the recruitment process.

Topics

python nlp ocr hr tf-idf recruitment resume-screening ai-assistant

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages