ai-recruitment-agent 0.1.0

CLI tool to screen CVs against a Job Description using Google Gemini and Notion

AI Recruitment Scanning Agent

A CLI tool that screens CVs against a Job Description using Google Gemini and populates a Notion database with ranked candidate profiles.

Stack

• Python 3.9+ with Typer CLI
• Google Gemini 1.5 Flash — JD parsing + CV analysis
• Notion API — candidate record storage
• pdfplumber / python-docx — PDF and DOCX text extraction

Setup

# 1. Clone and enter the repo
git clone <repo-url> && cd ai-recruitment-cli-agent

# 2. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment variables
cp .env.example .env

Edit .env:

GOOGLE_GEMINI_API_KEY=your_gemini_api_key
NOTION_API_KEY=your_notion_integration_secret
DEFAULT_NOTION_DB_ID=your_notion_database_id

Notion Setup

1. Create an integration at notion.so/my-integrations with Read, Insert, and Update permissions.
2. Share your target database with the integration (database ••• > Connections).
3. Required database properties:

Property	Type
Candidate Name	Title
Email	Email
Contact Number	Phone
Skills	Multi-select
Position Title (JD)	Text
Job ID (JD)	Text
Experience Summary	Text
AI Ranking Reason	Text
Match Score	Number
Ranking Category	Select (High Fit, Medium Fit, Low Fit)
Status	Select (New - AI Processed)
CV Filename	Text
Processing Date	Date

Usage

# Show help
python main.py
python main.py process --help

# Run
python main.py process <CV_FOLDER> <JD_PDF> [--notion-db-id <DB_ID>]

# Example
python main.py process ./cvs/ ./jds/job_description.pdf --notion-db-id xxxx-xxxx-xxxx

--notion-db-id overrides DEFAULT_NOTION_DB_ID from .env.

What it does

1. Validates API keys and Notion database access on startup.
2. Extracts text from the JD PDF and pulls out Position Title and Job ID via Gemini.
3. Iterates all .pdf and .docx files in the CV folder.
4. For each CV: extracts text, sends to Gemini with the JD for scoring (0–100), ranking, and structured field extraction.
5. Checks Notion for duplicates by email + Job ID before inserting.
6. Prints a summary table of processed / skipped / failed counts.

Tests

pip install pytest pytest-mock
pytest tests/ -v

Troubleshooting

Issue	Fix
GOOGLE_GEMINI_API_KEY not found	Check .env is present and key is valid
NOTION_API_KEY not found	Verify integration secret in .env
Notion initialization failed	Confirm database is shared with the integration
Could not extract text from JD PDF	PDF may be scanned/password-protected
Duplicate entries appearing	Ensure Email and Job ID (JD) properties exist with exact names