otniel113/autocvselector

1. Repository purpose

- This is a batch-oriented CV screening pipeline for high-volume hiring, not a web app.

- The system turns a single job description plus a folder of candidate resumes into ranked hiring recommendations.

2. High-level architecture

- The code is split into three sequential stages, each with a clear boundary:

- JD extraction and structuring

- semantic similarity screening

- LLM-based final evaluation and ranking

- Intermediate outputs are persisted to disk so each phase can be rerun independently.

3. Input layer

- The main inputs live under two folders:

- JobDesc/ for the vacancy source document

- CVs/ for candidate resume files

- The repo includes both PDF and Markdown versions of documents, indicating a conversion/parsing step before scoring.

- Vacancy_criteria.json and screening_results.json are intermediate artifacts produced by the pipeline.

4. Phase 1: Job description extraction

- step1_extract_jd.py is the first transformation boundary.

- It converts the raw job description into a structured criteria JSON representation.

- The README indicates this stage uses Gemini to extract hard skills, soft skills, and experience requirements into a machine-readable schema.

- Output is stored in JobDesc/Vacancy_criteria.json.

5. Phase 2: Resume parsing and fast screening

- step2_similarity_screening.py performs the first candidate reduction pass.

- Candidate resumes in CVs/ are parsed into text-friendly form; the README says this uses LlamaParse for high-fidelity PDF parsing.

- The screening logic uses Hugging Face embeddings with BAAI/bge-m3 and cosine similarity to compare each CV against the JD criteria.

- This phase is the cost-saving filter that removes low-relevance candidates before any expensive LLM reasoning.

6. Phase 3: Deep evaluation and ranking

- step3_gemini_evaluation.py consumes the shortlisted candidates and performs a deeper assessment.

- The README describes this as a Gemini 3 Flash “senior recruiter” evaluation step.

- This stage appears to do more nuanced scoring, including experience calculation, degree synonym recognition, and compensation logic for non-traditional but strong candidates.

7. Data flow between stages

- The pipeline flows from raw documents → structured criteria → similarity scores → final ranked report.

- The key persisted handoff points are:

- Vacancy_criteria.json from phase 1

- screening_results.json from phase 2

- final_evaluation_results.json from phase 3

- This file-based orchestration makes the system easy to run as standalone scripts without a service layer.

8. External dependencies and service boundaries

- The architecture depends on three external AI services:

- LlamaParse for document parsing

- Hugging Face Inference API for embeddings

- Google Gemini API for extraction and final reasoning

- API keys are loaded from .env, with .env.example acting as the configuration template.

9. Local compute and library layer

- The runtime is Python 3.10+, with 3.11 recommended.

- requirements.txt points to a lightweight ML/data stack, including numpy, scikit-learn, pydantic, huggingface-hub, and python-dotenv.

- This suggests most orchestration and scoring logic is local, while the heavy AI capabilities are delegated to hosted APIs.

10. Outputs and operational model

- The final deliverable is final_evaluation_results.json, which contains the ranked candidate list and reasoning.

- Because the repo stores both intermediate and final artifacts, the system is designed for auditable screening, where each stage can be inspected separately.

- The architecture is optimized for high-volume offline processing rather than interactive, real-time candidate review.