Metadata-Version: 2.4
Name: ai-recruitment-agent
Version: 0.1.0
Summary: CLI tool to screen CVs against a Job Description using Google Gemini and Notion
Project-URL: Homepage, https://github.com/kneeraazon404/ai-recruitment-cli-agent
Project-URL: Repository, https://github.com/kneeraazon404/ai-recruitment-cli-agent
Project-URL: Issues, https://github.com/kneeraazon404/ai-recruitment-cli-agent/issues
Author: kneeraazon404
License: MIT
Keywords: ai,cli,cv,gemini,notion,recruitment,screening
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: google-generativeai>=0.5.0
Requires-Dist: notion-client>=2.0.0
Requires-Dist: pdfplumber>=0.10.0
Requires-Dist: python-docx>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: typer[all]>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://typer.tiangolo.com/) CLI
- **Google Gemini 1.5 Flash** — JD parsing + CV analysis
- **Notion API** — candidate record storage
- **pdfplumber** / **python-docx** — PDF and DOCX text extraction

## Setup

```bash
# 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`:

```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](https://www.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

```bash
# 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

```bash
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 |
