AI Resume Screener.

Project Overview

Ranks résumés against a job description by semantic relevance — a first-pass filter for a mountain of applications, built with fairness in mind.

A single job opening can draw hundreds or thousands of résumés, and reading them all is a genuine bottleneck — so recruiters need a way to surface the most relevant candidates first. This project builds an AI résumé screener that ranks résumés against a job description by semantic relevance, giving a sorted shortlist as a first-pass filter. It is a practical NLP application — but one that must be built with unusual care, because ranking people's applications is a domain where a careless model can do real harm, and this project treats fairness as a first-class requirement, not an afterthought.

The core is text relevance scoring. Both the job description and each résumé are turned into a representation of their meaning — from simple keyword/TF-IDF matching up to semantic embeddings that capture meaning beyond exact words (so "managed a team" matches "team leadership") — and each résumé is scored by how well it matches the job, then ranked. Better systems match on skills and requirements rather than surface keywords, reducing the "keyword-stuffing" gameability of naïve matchers, and can explain why a résumé scored as it did.

The value is a faster first pass over a large applicant pool. But the honesty here is paramount and non-negotiable: hiring models are notorious for learning and amplifying bias from historical data (a famous case scrapped a tool that penalised résumés containing "women's"), so this must be built to assist, not decide — a ranking aid that a human reviews, never an automated reject; it should avoid training on biased outcome labels, be tested for disparate impact across protected groups, focus on job-relevant skills, and keep a human firmly in the loop. Regulations increasingly govern automated hiring, too. Built with those guardrails front and centre, it is a genuinely useful relevance tool and an essential lesson in doing applied NLP responsibly in a high-stakes domain.

What this project does

• Ranks résumés against a job description by relevance
• Scores text similarity (keywords → semantic embeddings)
• Matches on skills/requirements, not just surface keywords
• Produces a sorted shortlist as a first-pass filter
• Explains why a résumé scored as it did
• Assists human reviewers — never auto-rejects
• Is built and tested for fairness

Real-World Applications

Deployment contexts where a build of this kind earns its keep.

Features & Capabilities

• Semantic relevance scoring/ranking
• Skill/requirement matching
• Explainable scores
• Human-in-the-loop, assist-not-decide design
• Bias testing (disparate impact)
• Job-relevant, gameability-resistant matching
• Honest about hiring bias and regulation

Difficulty, Time & Required Skills

Skills you should have (or will pick up)

• Text representation (TF-IDF, embeddings)
• Semantic similarity/relevance ranking
• Skill/requirement extraction and matching
• Explainability of scores
• Fairness testing and responsible deployment

Bill of Materials

Every part below is commonly available from Indian and international hobby-electronics suppliers. Prices are indicative 2026 retail figures in Indian rupees and will drift — treat them as a budgeting guide, not a quotation.

Estimated total: ₹0, excluding tools, shipping and consumables.

Tools and consumables

• Soldering iron (temperature controlled, 350 °C) with 0.8 mm 60/40 or lead-free solder
• Digital multimeter — continuity, DC volts and current ranges
• Wire strippers, flush cutters and a small set of precision screwdrivers
• Heat-shrink tubing and a heat gun (or a lighter, carefully)
• A laptop with a USB port and the toolchain listed above

Hardware Specifications

This is a pure-software NLP system — there is no electronic hardware to specify. The "platform" is a computer: a CPU is sufficient for embedding-based scoring at modest scale, while a GPU speeds up transformer embedding of very large résumé pools.

Memory and storage scale with the applicant pool and the embedding index; a server deployment adds the recruiter-facing review UI and an audit/fairness-logging store. Everything else lives in the software stack, libraries and models below.

Software Requirements & Development Environment

Reference toolchain: Python 3.11 + NLP (embeddings/transformers). Anything newer normally works; anything older may lack the board definitions used here.

• Install the Arduino IDE 2.3.x (or PlatformIO if you prefer a real editor and dependency locking).
• Add https://espressif.github.io/arduino-esp32/package_esp32_index.json under File → Preferences → Additional Board Manager URLs, then install esp32 from the Boards Manager.
• Set the correct port under Tools → Port. On Linux add yourself to the dialout group: sudo usermod -aG dialout $USER and log out and back in.
• Open the Serial Monitor at 115200 baud — every sketch here logs its state there.
• Keep File → Preferences → Show verbose output during: compilation switched on while you are debugging build errors.

Required libraries

Block Diagram

The block diagram shows the functional decomposition of the system — what senses, what decides, what acts, and where the data ends up.

Circuit Diagram & Wiring

The "wiring" is the ranking data flow — the job description and each résumé are embedded, scored for relevance, ranked, and presented to a human with explanations and fairness checks.

Wire one row at a time and tick it off — most "it does not work" reports trace back to a single swapped pair.

Wiring explanation

• Represent the job description and résumés as text embeddings (or skill sets).
• Score each résumé's relevance to the job; rank.
• Match on job-relevant skills/requirements, not surface keywords.
• Present a ranked shortlist with explanations to a human reviewer.
• Test for disparate impact and keep a human in the loop — assist, not decide.

System Architecture

Read the stack from the bottom up: physical hardware, the firmware that drives it, the transport that moves data off the device, and the software a human actually looks at.

Working Principle

The résumé screener is, technically, a text-relevance ranking problem — score how well each résumé matches a job description and sort — but it is defined at least as much by its ethics as its algorithm, because it ranks people's applications. That framing has to come first: a naïve or biased ranker does not merely make errors, it can systematically disadvantage real candidates, so fairness and human oversight are requirements of the design, not features added later. A responsible screener is deliberately scoped as an assistant that helps a human review a large pool faster, never as an automated gatekeeper that rejects people.

The relevance core sits on a spectrum of sophistication. At the simple end, keyword or TF-IDF matching counts overlapping terms — easy, but shallow and gameable (candidates keyword-stuff, and "led a team" fails to match "team leadership"). At the better end, semantic embeddings represent the job and each résumé by meaning: a model maps text to vectors where semantically similar content is close, so relevance is a similarity between meanings, capturing paraphrase and synonymy that keyword matching misses. Best of all is matching on extracted skills and requirements — decomposing the job into what it actually needs and checking each résumé against those — which is both more accurate and more explainable (you can show which requirements a résumé meets), and harder to game with keyword stuffing.

Explainability matters here more than in most ranking tasks, precisely because the stakes are human. A score with no reason ("candidate X: 0.72") is neither useful to a recruiter nor auditable for fairness. Showing why — which skills matched, which requirements are met or missing — turns the tool into genuine decision support a human can sensibly review and override, and provides a handle for checking that the model is keying on job-relevant factors rather than spurious ones.

The non-negotiable part is bias, and the history is a warning. Hiring models trained on historical hiring decisions learn and amplify the biases in that history — most famously, a large company scrapped an experimental résumé tool after it learned to penalise résumés containing the word "women's" and downgrade graduates of women's colleges, because it had been trained on a male-dominated hiring history. The lessons are concrete and must be built in: do not naïvely train on biased outcome labels; test for disparate impact across protected groups (does the ranking systematically disadvantage a group?); focus scoring on job-relevant skills and strip or ignore proxies for protected characteristics; keep a human firmly in the loop making the actual decisions; and be aware that automated hiring is increasingly regulated (bias audits, candidate notice). Built with all of that in front — a semantic, skill-based, explainable relevance ranker, tested for fairness, positioned as an assistant to human reviewers — it delivers real value (a faster, better first pass over a mountain of applications) while standing as the project's central lesson: doing applied NLP responsibly where the output affects people's lives.

The maths behind it

Semantic relevance

v_job    = embed(job_description)
v_resume = embed(resume)

  relevance = cosine(v_job, v_resume)   # meaning, not keywords

rank résumés by relevance → shortlist (first pass).

Skill/requirement matching (better)

reqs = extract_skills(job)
for each résumé:
  met = { r in reqs : résumé demonstrates r }
  score = |met| / |reqs|   (weighted by importance)
  explanation = met vs missing   # explainable + less gameable

Fairness (non-negotiable)

assist, do NOT decide — human reviews every outcome
do NOT train on biased outcome labels
test disparate impact:
  selection_rate(group_A) / selection_rate(group_B) ≈ 1
strip proxies for protected attributes; audit regularly.

Program Flowchart

The firmware is a single cooperative loop. Nothing blocks for long, so networking, sensing and the user interface all stay responsive.

Assembly Instructions

Build on a breadboard first and only commit to solder once the whole system has run for an hour without a fault.

1. Build explainable relevance scoring

   Represent the job and résumés semantically, extract job-relevant skills/requirements, and score/rank with explanations of what matched.

2. Add fairness testing

   Measure disparate impact across groups, investigate and mitigate any systematic disadvantage, and keep scoring on job-relevant factors.

3. Deploy with human oversight

   Present an explainable shortlist to human reviewers who make the decisions, and comply with applicable hiring regulations.

Step-by-Step Implementation Guide

Work through these in order. Each step ends in something you can observe, so a failure is always localised to the step you just finished.

1. Score relevance with explanations

   Score each résumé's semantic relevance and skill match to the job, ranking with explicit met/missing reasons.

   pythonrank.py Copy Download

   import numpy as np
   
   def cosine(a, b):
       return float(np.dot(a, b) / (np.linalg.norm(a)*np.linalg.norm(b) + 1e-9))
   
   def rank(job, resumes, embed, skills_of):
       reqs, jv = skills_of(job), embed(job)          # job-relevant requirements
       out = []
       for r in resumes:
           met = [s for s in reqs if s in skills_of(r)]     # explainable
           out.append({"id": r.id,
                       "score": round(cosine(jv, embed(r)), 3),   # semantic relevance
                       "met": met,
                       "missing": [s for s in reqs if s not in met]})
       return sorted(out, key=lambda x: x["score"], reverse=True)   # shortlist

   reqs, jv = skills_of(job), embed(job) # job-relevant requirementsScoring is anchored to job-relevant requirements, keeping the model on legitimate factors rather than spurious signals.

   met = [s for s in reqs if s in skills_of(r)] # explainableRecording which requirements a résumé meets makes the score explainable and auditable — essential in a hiring context.

   "score": round(cosine(jv, embed(r)), 3), # semantic relevanceSemantic relevance captures meaning beyond keywords, so paraphrased experience still matches.

   return sorted(out, key=lambda x: x["score"], reverse=True) # shortlistThe output is a ranked shortlist for a human first pass — a filter, not a decision.

2. Test fairness and keep humans in the loop

   Measure disparate impact across groups, mitigate issues, and route the explainable shortlist to human reviewers who decide.

Complete Source Code

The listing below is complete and compiles as written — there are no elided sections. Read the annotations under each block before you upload it.

#!/usr/bin/env python3
"""
AI Résumé Screener (fairness-first)

Ranks résumés against a job description by SEMANTIC, SKILL-BASED
relevance, with explanations, as a first-pass filter. ASSIST, NOT
DECIDE: a human reviews every outcome. Tested for disparate impact;
no training on biased outcomes; no protected-attribute proxies.
"""
import numpy as np

def cosine(a, b):
    return float(np.dot(a, b) / (np.linalg.norm(a)*np.linalg.norm(b) + 1e-9))

class ResumeScreener:
    def __init__(self, embed, skills_of):
        self.embed = embed; self.skills_of = skills_of

    def rank(self, job, resumes):
        reqs = self.skills_of(job)                 # job-relevant requirements only
        jv = self.embed(job)
        results = []
        for r in resumes:
            met = [s for s in reqs if s in self.skills_of(r)]
            results.append({
                "id": r.id,
                "score": round(cosine(jv, self.embed(r.text)), 3),  # semantic
                "skills_met": met,                                   # explainable
                "skills_missing": [s for s in reqs if s not in met],
            })
        results.sort(key=lambda x: x["score"], reverse=True)
        return results                             # ranked shortlist (first pass)

    def fairness_report(self, ranked, group_of, top_k):
        # disparate impact: selection rate by group in the top-k shortlist
        shortlisted = {r["id"] for r in ranked[:top_k]}
        rates = {}
        for gid, members in groups(group_of).items():
            rates[gid] = len(members & shortlisted) / max(len(members), 1)
        return rates                               # audit vs 4/5ths rule etc.

if __name__ == "__main__":
    scr = ResumeScreener(embed_model, extract_skills)
    ranked = scr.rank(JOB, RESUMES)
    # A HUMAN reviews 'ranked' and decides. Check scr.fairness_report(...).
    # No auto-reject. Comply with automated-hiring regulations.

Configuration & Calibration

Configuration steps

• Configure the embedding model and skills/requirements extraction.
• Configure relevance scoring, weighting and shortlist size.
• Configure the fairness/disparate-impact tests and thresholds.
• Configure human-review workflow and regulatory compliance.

Calibration procedure

An uncalibrated sensor produces confident, precise, wrong numbers. Do this once per physical unit and record the constants.

1. Relevance quality

   Have reviewers judge whether the shortlist surfaces genuinely relevant candidates.

2. Fairness

   Measure disparate impact across groups; investigate and mitigate any systematic gaps.

3. Explanations

   Verify explanations are accurate and job-relevant, supporting human review.

Dataset, Model & Training

Dataset

Job descriptions and résumés (text); a skills/requirements taxonomy; embedding model for semantic representation.

Critically: do NOT train relevance on biased historical hiring outcomes. Use job-relevant skill matching and a fairness test set.

Data preprocessing

• Parse résumés/job descriptions to text; extract skills/requirements.
• Avoid ingesting protected attributes or their proxies for scoring.
• Normalise text; embed for semantic matching.

Hyperparameters

Training process

• Prefer unsupervised semantic matching + curated skill rules over training on biased outcome labels.
• If any learning is used, exclude protected attributes/proxies and validate fairness.
• Continuously test disparate impact and explanations.

Evaluation, Metrics & Deployment

Beyond relevance quality, the decisive metrics are fairness (disparate impact across groups) and the presence of meaningful human oversight.

Figures from the reference training run described above — reproduce them before trusting your own changes.

Inference example

import numpy as np

def relevance(job_vec, resume_vec):
    return float(np.dot(job_vec, resume_vec) /
                 (np.linalg.norm(job_vec) * np.linalg.norm(resume_vec) + 1e-9))

def screen(job, resumes, embed, skills_of):
    reqs = skills_of(job)                          # job-relevant requirements
    jv = embed(job)
    ranked = []
    for r in resumes:
        met = [s for s in reqs if s in skills_of(r)]     # explainable match
        score = relevance(jv, embed(r))                  # semantic relevance
        ranked.append({
            "resume": r.id, "score": round(score, 3),
            "skills_met": met, "skills_missing": [s for s in reqs if s not in met],
        })
    ranked.sort(key=lambda x: x["score"], reverse=True)  # first-pass shortlist
    return ranked
    # ASSIST, NOT DECIDE: a human reviews; test disparate impact; no auto-reject.

Testing Procedure & Expected Output

Test from the bottom up. Confirm power, then each sensor in isolation, then the integrated loop — the first failing step tells you exactly where to look.

Bench-test checklist. If a row fails, stop and fix it before moving on.

Expected output

An explainable, fairness-tested ranked shortlist for human reviewers — a first-pass filter, not a decision.

{
  "job": "Backend Engineer",
  "top": [
    { "id": "R-108", "score": 0.86, "skills_met": ["Python","APIs","SQL"], "skills_missing": ["Kubernetes"] },
    { "id": "R-042", "score": 0.81, "skills_met": ["Python","SQL"], "skills_missing": ["APIs","Kubernetes"] }
  ],
  "note": "assist, not decide — human reviews; disparate impact tested"
}

A ranked shortlist with explicit matched/missing skills per candidate — a fast, explainable first pass that a human reviews, tested for fairness rather than trusted blindly.

Troubleshooting: Common Errors & Fixes

Performance Optimisation

• Prefer semantic, skill-based matching over keywords.
• Make scores explainable for human review.
• Test disparate impact continuously; mitigate bias.
• Keep a human in the loop — assist, not decide.
• Replace every delay() with a millis() comparison — blocking delays are the single most common cause of dropped readings.
• Sample sensors on a fixed cadence and publish on a slower one; you almost never need to transmit at the sampling rate.
• Move networking into its own FreeRTOS task so a slow DNS lookup cannot stall the control loop.
• Use uint8_t / uint16_t where the range allows; on an 8-bit AVR a 32-bit add costs four times as much.
• Profile before optimising — print micros() deltas around each stage and fix the slowest one first.

Safety Precautions

• Assist, do not decide — never auto-reject; a human makes every hiring decision.
• Do not train on biased historical outcomes; exclude protected attributes and their proxies.
• Test and monitor for disparate impact; hiring AI is prone to amplifying bias.
• Comply with automated-hiring regulations (bias audits, candidate notice).
• Wear eye protection when soldering or cutting, and solder in a ventilated space — rosin flux fumes are a respiratory irritant.
• Power the circuit through a bench supply with a current limit while you are testing. A 300 mA limit turns a wiring mistake into a beep instead of a dead board.
• Disconnect power before changing any wiring. Hot-plugging a sensor onto a live bus is the fastest way to lose a controller.

Maintenance

• Re-test fairness regularly and after any change.
• Update the skills taxonomy and embeddings.
• Audit explanations and reviewer feedback.
• Track regulatory changes for automated hiring.
• Re-check every screw terminal and header after the first week — thermal cycling loosens connections that felt tight on day one.
• Recalibrate at the interval given in the calibration section, and keep the constants in a text file next to the firmware — not only in flash.
• Keep a short logbook of firmware versions and what changed. Six months later you will not remember why that constant is 1.083.

Future Improvements & Upgrades

A working v1 is a platform, not a finish line. These are the upgrades that add the most capability for the least rework.

• Add structured skill extraction and evidence linking.
• Add counterfactual/fairness explanations.
• Add reviewer feedback loops (without learning bias).
• Add multilingual résumé support.
• Design a proper PCB. Once the breadboard version has run for a month, moving to a two-layer board removes the intermittent-contact failures that dominate prototype faults.
• Add connectivity — an ESP32 and an MQTT publish turn a local gadget into something you can graph, alert on and analyse over months.
• Add persistent local storage (microSD or the on-chip flash) so a network outage does not create a hole in your data.
• Move configuration out of the source: a captive-portal setup page or a JSON config file makes the build reusable without a recompile.
• Add a battery and solar option so the unit survives a power cut and can be sited away from a socket.
• Write a small test harness that feeds synthetic sensor values through the decision logic, so you can validate thresholds without physically triggering the event.

Frequently Asked Questions

References & Learning Resources

These are the primary sources worth reading in full. Manufacturer datasheets always outrank forum posts when the two disagree.

1. Text similarity / embeddingsReference
2. Algorithmic bias in hiringReference
3. Disparate impactReference
4. TF-IDFReference
5. Responsible AI in hiringReference