AI Recruitment Scanning Agent
A CLI tool that screens CVs against a Job Description using Google Gemini 1.5 Flash and pushes ranked candidate profiles into a Notion database — one command, zero manual effort.
PyPI: https://pypi.org/project/ai-recruitment-agent/
Install
pip install ai-recruitment-agent
Configure
Copy .env.example to .env and fill in your credentials:
GOOGLE_GEMINI_API_KEY=your_gemini_api_key
NOTION_API_KEY=your_notion_integration_secret
DEFAULT_NOTION_DB_ID=your_notion_database_id
Where to get these:
| Key | Source |
|---|---|
GOOGLE_GEMINI_API_KEY |
https://aistudio.google.com/app/apikey |
NOTION_API_KEY |
https://www.notion.so/my-integrations → New integration → copy secret |
DEFAULT_NOTION_DB_ID |
Your Notion database URL: notion.so/yourname/THIS-PART?v=... |
Setup Notion Database
Run once to add all required properties to your Notion database automatically:
ai-recruit setup-notion
# or with an explicit database ID:
ai-recruit setup-notion --notion-db-id xxxx-xxxx-xxxx-xxxx
Prerequisite: Share your Notion database with the integration first — open the database →
•••menu → Connections → add your integration.
The command adds 13 properties (Email, Skills, Match Score, Ranking Category, etc.), renames the title column to Candidate Name, and skips anything already present.
Run
ai-recruit process <CV_FOLDER> <JD_PDF> [--notion-db-id <DB_ID>]
# Basic — reads DB ID from .env
ai-recruit process ./cvs/ ./jd.pdf
# Override Notion database
ai-recruit process ./cvs/ ./jd.pdf --notion-db-id xxxx-xxxx-xxxx-xxxx
# Other commands
ai-recruit setup-notion --help
ai-recruit --version
ai-recruit --help
ai-recruit process --help
What it does
- Validates API keys and Notion database access on startup.
- Reads the JD PDF — extracts position title and job ID via Gemini.
- Iterates all
.pdfand.docxfiles in the CV folder with a live progress bar. - For each CV: extracts text → sends to Gemini → receives a score (0–100), ranking (
High Fit/Medium Fit/Low Fit), and structured candidate data. - Checks Notion for duplicates by email + job ID before inserting.
- Pushes a new page to your Notion database for each unique candidate.
- Prints a summary table of processed / skipped / failed counts.
Troubleshooting
| Error | Fix |
|---|---|
GOOGLE_GEMINI_API_KEY not found |
Check .env exists in your working directory and the key is valid |
NOTION_API_KEY not found |
Verify the integration secret in .env |
Notion initialization failed |
Confirm the database is shared with your integration |
Could not extract text from JD PDF |
PDF may be scanned, image-based, or password-protected |
| Duplicate entries appearing | Ensure Email and Job ID (JD) properties exist with exact names |
| Gemini API error | Check your quota at aistudio.google.com |
Metadata
Release files for ai-recruitment-agent 0.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_recruitment_agent-0.3.2.tar.gz | 9.5 kB | Without provenance | Details for ai_recruitment_agent-0.3.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_recruitment_agent-0.3.2-py3-none-any.whl | Python 3 | none | any | Details for ai_recruitment_agent-0.3.2-py3-none-any.whl |
Total release size: 20.1 kB
Release files / ai_recruitment_agent-0.3.2.tar.gz
| Download URL | ai_recruitment_agent-0.3.2.tar.gz |
|---|---|
| Size | 9.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
275d13c9ab783d974304ae483a7de6074d1f2316f3c5122885a42c462d50cfe6
|
|
BLAKE2b-256 checksum How to use checksums |
3449b16d817430622ea5e862110cd14de21404820969f8633fa3a9b5c64f260e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / ai_recruitment_agent-0.3.2-py3-none-any.whl
| Download URL | ai_recruitment_agent-0.3.2-py3-none-any.whl |
|---|---|
| Size | 10.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e349f9a435492a87e531520646731ff53980806e359084f300f2a2d6820e1e8b
|
|
BLAKE2b-256 checksum How to use checksums |
f331db3c6f7e75ffb93d1953a13558f1f93c30e0a1bc92663d6be3fa78362787
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Security for ai-recruitment-agent 0.3.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.