AI Resume Screening Project: Rank Resumes Against a Job Description in Python

How to build an AI resume screener in Python, step by step

1. Step 1. Set up the project and sample data

   Create the folder structure and install the libraries.

   mkdir resume-screener && cd resume-screener
   python -m venv .venv
   # Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
   pip install pypdf scikit-learn sentence-transformers pandas
   mkdir resumes

   Put your sample PDF resumes in the resumes folder and paste a real-looking job description (for example a data analyst fresher role) into job_description.txt. Make the resumes varied: strong matches, partial matches, clear mismatches, and a couple that use different wording for the same skills.

2. Step 2. Extract text from the PDF resumes

   pypdf reads the text layer of each PDF. The warning catches scanned resumes, which contain images instead of text.

   # extract.py
   import re
   from pathlib import Path
   from pypdf import PdfReader
   
   def pdf_text(path):
       reader = PdfReader(path)
       text = " ".join((page.extract_text() or "") for page in reader.pages)
       return re.sub(r"\s+", " ", text).strip()
   
   def load_resumes(folder="resumes"):
       resumes = {}
       for pdf in sorted(Path(folder).glob("*.pdf")):
           text = pdf_text(pdf)
           if len(text.split()) < 50:
               print(f"Warning: {pdf.name} has almost no text (scanned PDF?)")
           resumes[pdf.name] = text
       return resumes
   
   def load_jd(path="job_description.txt"):
       return Path(path).read_text(encoding="utf-8")

   Print the extracted text of two or three resumes. Two-column layouts sometimes come out with lines interleaved, which you should note as a limitation.

3. Step 3. Rank resumes with TF-IDF cosine similarity

   TF-IDF gives each word a weight that is high when it is frequent in one document but rare across all documents. Cosine similarity then measures how closely a resume's word profile matches the job description's.

   # score_tfidf.py
   from sklearn.feature_extraction.text import TfidfVectorizer
   from sklearn.metrics.pairwise import cosine_similarity
   
   def tfidf_scores(jd, resumes):
       names = list(resumes)
       vec = TfidfVectorizer(stop_words="english", ngram_range=(1, 2), sublinear_tf=True)
       matrix = vec.fit_transform([jd] + [resumes[n] for n in names])
       sims = cosine_similarity(matrix[0], matrix[1:])[0]
       return dict(zip(names, sims))
   
   if __name__ == "__main__":
       from extract import load_resumes, load_jd
       scores = tfidf_scores(load_jd(), load_resumes())
       for name, s in sorted(scores.items(), key=lambda x: -x[1]):
           print(f"{s:.3f}  {name}")

   Run python score_tfidf.py. Your first ranking is ready. Notice its weakness: a resume that says "Postgres" scores nothing for a job description that says "SQL".

4. Step 4. Add semantic matching with sentence-transformers

   Embedding models compare meaning rather than exact words. all-MiniLM-L6-v2 reads at most 256 word pieces at a time, so a whole resume would be cut off. Instead, we split the job description into requirement lines, split each resume into chunks, and ask: for each requirement, how well does the best-matching chunk cover it?

   # score_semantic.py
   import re
   from sentence_transformers import SentenceTransformer
   
   model = SentenceTransformer("all-MiniLM-L6-v2")
   
   def chunks(text, size=120):
       words = text.split()
       return [" ".join(words[i:i + size]) for i in range(0, len(words), size)] or [""]
   
   def requirements(jd):
       lines = [l.strip(" -*\t") for l in re.split(r"[\n.;]", jd)]
       return [l for l in lines if len(l.split()) >= 4]
   
   def semantic_scores(jd, resumes):
       reqs = model.encode(requirements(jd), normalize_embeddings=True)
       scores = {}
       for name, text in resumes.items():
           parts = model.encode(chunks(text), normalize_embeddings=True)
           sim = model.similarity(reqs, parts)  # rows: requirements, columns: chunks
           scores[name] = float(sim.max(dim=1).values.mean())
       return scores

   Averaging the best match per requirement means a resume cannot score high by repeating one skill many times. It has to cover most of the requirements.

5. Step 5. Extract skills with a keyword list

   Scores alone do not tell a recruiter why a candidate ranked high. A skill list does. Each skill has aliases, and the regex checks word boundaries so "excel" does not match "excellent" and "ml" does not match "html".

   # skills.py
   import re
   
   SKILLS = {
       "python": ["python"],
       "sql": ["sql", "mysql", "postgresql", "postgres"],
       "excel": ["excel", "spreadsheets"],
       "power bi": ["power bi", "powerbi"],
       "tableau": ["tableau"],
       "statistics": ["statistics", "statistical analysis"],
       "machine learning": ["machine learning", "ml", "scikit-learn"],
       "deep learning": ["deep learning", "pytorch", "tensorflow"],
       "communication": ["communication", "presentation"],
       "git": ["git", "github"],
   }
   
   def find_skills(text):
       text = text.lower()
       found = set()
       for skill, aliases in SKILLS.items():
           for a in aliases:
               if re.search(rf"(?<![a-z0-9]){re.escape(a)}(?![a-z0-9])", text):
                   found.add(skill)
                   break
       return found

   Extend the dictionary for each role you test. Keeping it as plain data, not a black box, means anyone can audit what the screener looks for.

6. Step 6. Combine the scores into a ranked table

   TF-IDF and embedding scores sit on different scales, so we rescale each to 0 to 1 across candidates before combining them.

   # rank.py
   import pandas as pd
   from extract import load_resumes, load_jd
   from score_tfidf import tfidf_scores
   from score_semantic import semantic_scores
   from skills import find_skills
   
   jd, resumes = load_jd(), load_resumes()
   jd_skills = find_skills(jd)
   tf, sem = tfidf_scores(jd, resumes), semantic_scores(jd, resumes)
   
   rows = []
   for name, text in resumes.items():
       have = find_skills(text) & jd_skills
       rows.append({"resume": name, "tfidf": tf[name], "semantic": sem[name],
                    "skill_coverage": len(have) / max(len(jd_skills), 1),
                    "missing": ", ".join(sorted(jd_skills - have))})
   
   df = pd.DataFrame(rows)
   norm = lambda s: (s - s.min()) / (s.max() - s.min() + 1e-9)
   df["score"] = 0.4 * norm(df["semantic"]) + 0.3 * norm(df["tfidf"]) + 0.3 * df["skill_coverage"]
   df = df.sort_values("score", ascending=False).round(3)
   print(df.to_string(index=False))
   df.to_csv("ranking.csv", index=False)

   The weights (0.4, 0.3, 0.3) are a starting point, not a truth. Step 7 shows how to check whether they help, and your report should say how you chose them.

7. Step 7. Evaluate the ranking on a labelled set

   Ask two people (a senior, a placement coordinator or a friend in HR) to read your sample resumes against the job description and mark each one shortlist = 1 or 0. Save their decisions in labels.csv with columns resume and shortlist.

   # evaluate.py
   import pandas as pd
   from sklearn.metrics import roc_auc_score
   
   df = pd.read_csv("ranking.csv").merge(pd.read_csv("labels.csv"), on="resume")
   
   for col in ["tfidf", "semantic", "skill_coverage", "score"]:
       auc = roc_auc_score(df["shortlist"], df[col])
       top5 = int(df.nlargest(5, col)["shortlist"].sum())
       print(f"{col:15s} AUC {auc:.2f}   human-shortlisted in top 5: {top5}/5")

   AUC answers "how often does the method rank a shortlisted resume above a rejected one?" (1.0 is perfect, 0.5 is random). Top-5 hits answer the recruiter's real question. If the two humans disagree on some resumes, report that too: it shows the task itself is partly subjective.

8. Step 8. Run a simple fairness check

   A counterfactual test changes only a detail that should not matter and checks whether the score moves. Take one resume, create copies that differ only in a gender cue, and score all of them.

   # fairness_check.py
   from extract import load_resumes, load_jd
   from score_tfidf import tfidf_scores
   from score_semantic import semantic_scores
   
   jd, resumes = load_jd(), load_resumes()
   base = resumes[sorted(resumes)[0]]  # pick any resume
   
   variants = {
       "original": base,
       "women's club": base + " Captain of the women's coding club.",
       "men's club": base + " Captain of the men's coding club.",
   }
   for name, scores in [("tfidf", tfidf_scores(jd, variants)),
                        ("semantic", semantic_scores(jd, variants))]:
       print(name, {k: round(v, 4) for k, v in scores.items()})

   The two club variants should score the same. If they do not, your screener reacts to gender cues. Repeat with different names, college names and home towns, and report what you find, including the cases where scores did move.

Frequently asked questions

Keep learning

References

• scikit-learn: cosine_similarity documentation
• Sentence Transformers: semantic textual similarity
• all-MiniLM-L6-v2 model card (Hugging Face)
• BBC News: Amazon scrapped 'sexist AI' tool (2018)
• NYC Department of Consumer and Worker Protection: Automated Employment Decision Tools