https://github.com/adelsherif8/cv-analyzer
AI resume analyzer with RAG-grounded summaries — upload a CV + job description for OpenAI-powered scoring, skill-gap analysis & feedback. Next.js + FastAPI
https://github.com/adelsherif8/cv-analyzer
ai embeddings fastapi llm nextjs nlp openai python rag
Last synced: 1 day ago
JSON representation
AI resume analyzer with RAG-grounded summaries — upload a CV + job description for OpenAI-powered scoring, skill-gap analysis & feedback. Next.js + FastAPI
- Host: GitHub
- URL: https://github.com/adelsherif8/cv-analyzer
- Owner: adelsherif8
- Created: 2026-06-25T23:51:32.000Z (3 days ago)
- Default Branch: main
- Last Pushed: 2026-06-27T00:25:51.000Z (2 days ago)
- Last Synced: 2026-06-27T02:06:08.462Z (2 days ago)
- Topics: ai, embeddings, fastapi, llm, nextjs, nlp, openai, python, rag
- Language: Python
- Size: 1.02 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# CV Analyzer
> **Upload a resume + a job description, get an instant AI fit report.** Parses PDF/DOCX resumes, scores them against the role, and returns structured feedback on strengths, gaps, and matched skills — built for recruiters and candidates alike.
**▶️ Live demo:** _paste your URL here after deploy_ · 🚀 **Deploy it yourself in ~10 min:** [DEPLOY.md](./DEPLOY.md) (Vercel + Render, free)
---
## Features
- 📄 **Resume parsing** — extracts structured data from PDF and DOCX (PyMuPDF + `python-docx`)
- 🎯 **Fit scoring** — scores a candidate against a job profile with an explainable breakdown
- 🔎 **RAG-grounded summaries** — the CV is chunked, embedded, and the passages most relevant to the role are **retrieved** and used to ground the LLM summary (instead of blind truncation). Semantic retrieval via OpenAI embeddings when a key is set; dependency-free TF-IDF fallback otherwise. Retrieved passages are returned in the API response (`retrieved_context`)
- 🧠 **Skill-gap analysis** — surfaces matched skills, missing skills, and improvement feedback via a skill ontology
- 🧪 **Works without a key** — a built-in `mock_ai` mode returns realistic results offline, so the app is fully demoable without an OpenAI key
- 📤 **Exportable results** — structured JSON/report output for downstream use
## Tech Stack
- **Frontend:** Next.js 14 (App Router) + TypeScript + Tailwind CSS
- **Backend:** Python 3.11, FastAPI, OpenAI SDK (hand-built analysis *chains*, no framework lock-in)
- **RAG:** CV chunking + OpenAI `text-embedding-3-small` semantic retrieval (cosine over a NumPy matrix), with a pure-Python TF-IDF fallback — see [`app/services/rag.py`](./CV/backend/app/services/rag.py)
- **Parsing:** PyMuPDF (PDF), `python-docx` (Word)
## Repository Layout
```
CV/
├─ backend/ FastAPI service
│ └─ app/services/ parsing, analysis chains, skill ontology, mock AI
└─ frontend/ Next.js + Tailwind UI
```
## Quick Start
**Backend:**
```bash
cd CV/backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # add OPENAI_API_KEY (or leave blank for mock mode)
uvicorn app.main:app --reload # http://localhost:8000
```
**Frontend:**
```bash
cd CV/frontend
npm install
npm run dev # http://localhost:3000
```
## Configuration
The backend reads `OPENAI_API_KEY` from `CV/backend/.env`. A `.env.example` template is included; real `.env` files are git-ignored and never committed. With no key set, the app runs in **mock mode** so you can try the full flow instantly.