AI Recruiter Pro — High-Precision Multi-Domain Job Discovery & Verification Engine

AI Recruiter Pro is an open-source, evidence-grounded recruitment intelligence platform designed to discover, verify, score, and prepare job applications across multiple professional domains (including SAP EWM, Data Analytics, Python/Backend Engineering, and Mechanical & Industrial Systems).

The engine operates on a strict Human-Review-Only safety philosophy: it provides deep verification of vacancy authenticity, detects closed postings, computes deterministic ATS match scores, and builds tailored application packages while permanently disabling automated submission.

---

Public Release Information

• Repository: croxiee-007/Recruiter-Automation
• Visibility: Public (Clean orphan release branch)
• Current Stable Checkpoint: Phase 22.4 Verified Architecture
• Test Suite Pass Rate: 929 / 929 tests (100% passing)

---

Security & Privacy Model

This repository is strictly audited and packaged for public release:

• Zero API Keys / Secrets: No credentials, API tokens, or passwords are embedded in source code or Git history.
• Candidate Data Protection: Candidate resumes, uploads, session stores, and runtime databases are strictly excluded via .gitignore.
• Zero PII Exposure: All test suites utilize synthetic fixture candidates (candidate@example.com, +1 555-0199).
• Local Isolation: Candidate onboarding sessions and generated packages are stored in isolated runtime directories never committed to version control.

---

Strict Safety Invariants & Human-Review Disclaimer

Important

This software does NOT auto-apply to jobs.

The system permanently enforces the following safeguards in source code:

• auto_submit = False (Permanently hardcoded)
• submission_attempts = 0 (Permanently hardcoded)
• dry_run = True (Permanently hardcoded)
• human_review_required = True (Mandatory human approval)
• Browser Automation: DISABLED (Zero Selenium, Playwright, or automated form clicking)
• Exact Verification Safety Gate: Only vacancies confirmed as active with verified official employer URLs (VERIFIED_EXACT + active_status == True) can become application-ready.

---

Architecture Overview

                      +-----------------------------+
                      |   Candidate Profile Onboard |
                      |   - Resume Extraction       |
                      |   - Domain & Skill Analysis |
                      +--------------+--------------+
                                     |
                                     v
                      +-----------------------------+
                      |   Intelligent Search & QEx   |
                      |   - Domain Source Routing   |
                      |   - Source-Specific Queries |
                      +--------------+--------------+
                                     |
                                     v
                      +-----------------------------+
                      |   Live Discovery Radar      |
                      |   - Official Portals        |
                      |   - Public ATS (Greenhouse, |
                      |     Lever, Arbeitnow, etc.) |
                      +--------------+--------------+
                                     |
                                     v
                      +-----------------------------+
                      |   Job Verification Engine   |
                      |   - Canonical Normalization |
                      |   - Requisition Extraction  |
                      |   - Closed-Posting Semantic |
                      +--------------+--------------+
                                     |
                                     v
                      +-----------------------------+
                      |  Application Intelligence   |
                      |   - Deterministic ATS Score |
                      |   - Skill Gap Analysis      |
                      |   - Experience Calibration  |
                      |   - Sponsorship Evidence    |
                      +--------------+--------------+
                                     |
                                     v
                      +-----------------------------+
                      |   Recruiter Explainability  |
                      |   - Evidence-Grounded Dossier|
                      |   - Action Recommendations  |
                      |   - Decision Action Cards   |
                      +--------------+--------------+
                                     |
                                     v
                      +-----------------------------+
                      |   Dual-View Flask Dashboard |
                      |   - Job Hunt View           |
                      |   - Full Audit View         |
                      |   - Package Review Artifacts|
                      +-----------------------------+

---

Core System Modules

1. Intelligent Search & Query Expansion Engine (src/discovery/query_expansion_engine.py):

   • Expands candidate-calibrated search queries tailored per source (Greenhouse, Lever, Arbeitnow, Remotive, Official Careers).
   • Prevents developer-role leakage (e.g. Python skill $\neq$ Python Developer).

2. Official Job Verification Engine (src/verification/job_verification_engine.py):

   • Canonicalizes job URLs, validates employer and authorized ATS domain authority, and extracts exact requisition IDs.
   • Deterministically detects closed or expired vacancies via semantic status analysis.

3. Application Intelligence & Ranking Engine (src/scoring/application_intelligence_engine.py):

   • Multi-dimensional ranking combining ATS keyword scoring, structured skill gap breakdown, experience calibration, and evidence-grounded visa sponsorship analysis.

4. Recruiter Explainability & Decision Action Engine (src/ai/recruiter_explainer.py):

   • Generates deterministic, evidence-grounded recruiter review cards and dossiers covering why each role was picked, candidate strengths, skill gaps/flags, experience alignment, and action recommendations (RECOMMENDED_FOR_APPLICATION, REVIEW_REQUIRED, REJECTED_UNVERIFIED).

5. Multi-Domain Relevance & Scoring Engine (src/discovery/generic_relevance_engine.py, src/scoring/ats_scorer.py):

   • Calibrates role relevance, seniority tiers, experience fit, and domain alignment across diverse disciplines.

6. Session-Isolated Package Generator (src/tailoring/universal_package_generator.py):

   • Generates tailored resumes, cover letters, technical ATS reports, and Recruiter_Executive_Summary.txt dossiers isolated per candidate session.

7. Local / LAN Interactive Dashboard (src/app.py, src/templates/index.html):

   • Real-time Flask dashboard accessible locally and over Wi-Fi featuring interactive recruiter action cards and human-review package viewers.

---

Installation & Setup

Prerequisites

• Python 3.11+ (recommended: Python 3.13)
• macOS / Linux / Windows

Setup Environment

# Clone the repository
git clone https://github.com/croxiee-007/Recruiter-Automation.git
cd Recruiter-Automation

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -e .

---

Environment Variables

A sanitized configuration template is provided in .env.example:

cp .env.example .env

Available environment options:

HOST=0.0.0.0
PORT=5050
FLASK_ENV=production
DEBUG=False
AUTO_SUBMIT=False
DRY_RUN=True

---

Running Locally

Start the local dashboard daemon:

./start_dashboard.sh

Or run via Python:

PYTHONPATH=src venv/bin/python src/app.py

Open your browser at:

http://127.0.0.1:5050/landing

To stop the dashboard daemon:

./stop_dashboard.sh

---

Running Tests

Execute the comprehensive 929-test suite:

PYTHONPATH=src venv/bin/pytest tests/ -v

Or run targeted test suites:

# Recruiter Explainability & Decision Cards tests (Phase 22.4)
PYTHONPATH=src venv/bin/pytest tests/test_phase22_4_recruiter_explainability.py -v

# Operational Validation tests (Phase 22.3)
PYTHONPATH=src venv/bin/pytest tests/test_phase22_3_operational_validation.py -v

# Application Intelligence tests
PYTHONPATH=src venv/bin/pytest tests/test_phase22_3_application_intelligence.py -v

# Job Verification Engine tests
PYTHONPATH=src venv/bin/pytest tests/test_phase22_2_job_verification.py -v

# Query Expansion Engine tests
PYTHONPATH=src venv/bin/pytest tests/test_phase22_1_query_expansion.py -v

# Session Package Isolation tests
PYTHONPATH=src venv/bin/pytest tests/test_phase20_session_package_isolation.py -v

---

Project Status

• Phase 19: Multi-Candidate Onboarding, Session Isolation, Dynamic Domain Routing & LAN Serving.
• Phase 20: Universal Application Package Generator & Strict Server-Side Verification Gating.
• Phase 21 & 21.1: Profile Calibration, Experience Verification & Developer Leakage Prevention.
• Phase 22.1: Intelligent Search, Query Expansion & Multi-Source Translation.
• Phase 22.2: Central Job Verification Engine, Canonical Normalization & Requisition ID Extraction.
• Phase 22.3: Application Intelligence Engine, Multi-Dimensional Ranking, Sponsorship Evidence Grounding & Comprehensive Operational Validation.
• Phase 22.4: Recruiter Explainability Engine, Grounded Dossiers, Interactive Decision Action Cards & Executive Human-Review Artifacts.

---

Known Limitations

• Public ATS Coverage: Job posting extraction from career portals without open JSON APIs uses HTML heuristic and metadata parsing.
• Visa Sponsorship Transparency: Postings that omit explicit sponsorship statements are flagged as NOT_MENTIONED and require manual recruiter confirmation.

---

License

This project is open-source under the MIT License.