📄 AI Resume Analyzer

An AI-powered desktop CV analyzer built with Python & CustomTkinter — reads PDF/DOCX/TXT/image resumes, scores them with a deterministic NLP engine, and adds a Groq LLM hiring-screen verdict on top.

Python ve CustomTkinter ile geliştirilmiş, yapay zeka destekli bir masaüstü CV analiz aracı — PDF/DOCX/TXT/görsel CV'leri okur, deterministik bir NLP motoruyla puanlar ve üzerine bir Groq LLM'in işe alım kararını ekler.

🌐 English • 🇹🇷 Türkçe

---

🌐 English

---

📖 About

AI Resume Analyzer is a desktop application that analyzes resumes (PDF, DOCX, TXT, and even scanned/photographed PNG/JPG files) through a modern CustomTkinter interface. It runs the resume through a deterministic NLP scoring engine (analyzer.py) and, on top of that, sends the extracted facts and raw text to a Groq-hosted LLM (ai_advisor.py) which acts as an automated hiring screen — producing a hire/no-hire verdict, a detailed reasoning, strengths, risk factors, and missing information. The whole UI is bilingual (Turkish/English) and switches instantly.

✨ Features

Deterministic analysis engine (analyzer.py)

• Reads PDF (pdfminer.six → PyPDF2 fallback → OCR fallback for scanned/font-broken PDFs), DOCX (including tables), TXT, and PNG/JPG/JPEG (Tesseract OCR, Turkish + English)
• Automatically repairs mojibake (UTF-8 text mis-decoded as CP1252/Latin-1) and normalizes Unicode, so Turkish characters always render correctly
• Contact info extraction: email, phone, LinkedIn, GitHub, other portfolio links
• Categorized skill matching across 6 categories: programming languages, web/frameworks, databases, cloud/DevOps, data science/AI, soft skills
• Section-coverage detection (Contact, Summary, Experience, Education, Skills, Projects, Certifications, Languages) and Turkish-CV-specific extras (driver's license, military service status, references)
• Experience-year estimation from date ranges, education-level detection, action-verb and quantifiable-achievement analysis
• Optional job-description comparison — keyword match percentage and missing skills
• A weighted 0-100 score, a letter grade, and concrete, actionable suggestions

AI hiring advisor (ai_advisor.py)

• Sends the resume text plus the extracted facts to Groq and asks the model to act as an employer-side recruiter, not a career coach
• Returns a structured hire/no-hire verdict, reasoning, education/experience assessments, strengths, risk factors, missing information, suitable roles, and (when a job description is provided) a job-fit percentage
• Field-aware: never penalizes non-technical candidates (e.g. teachers, nurses) for missing a GitHub/portfolio link
• Gender-aware: never brings up Turkish military service status for candidates who appear to be female
• Fully resilient — if GROQ_API_KEY is missing or the API call fails, the app doesn't crash; the deterministic results keep showing and only the AI card reports the issue

Modern GUI (main.py)

• CustomTkinter-based, card-style layout with light/dark/system appearance modes
• Full Turkish/English UI switch (i18n.py) that re-renders instantly
• File picker + optional job-description textbox, analysis runs on a background thread so the UI never freezes
• Score card, colored skill chips, section checklist, job-match bar, and a dedicated AI verdict banner with strengths/risks/missing-info lists

🛠️ Tech Stack

• Python 3 — core language
• CustomTkinter — modern desktop GUI
• spaCy — tokenization, lemmatization, stopword filtering, sentence segmentation
• pdfminer.six + PyPDF2 — PDF text extraction (primary + fallback)
• PyMuPDF (fitz) — renders PDF pages to images for the OCR fallback path
• python-docx — DOCX text/table extraction
• pytesseract + Pillow (Tesseract OCR) — text extraction from scanned/photographed resumes
• Groq API — LLM-based hiring-screen feedback
• python-dotenv — loads secrets (API key) from environment variables

📸 Screenshots

CV	CV Analysis

Left: a sample resume fed into the app. Right: the resulting score, AI hiring verdict, strengths, risks, and missing info for that same resume.

⚙️ How it works

The project is a flat, four-module Python package (no sub-packages) plus a string table:

• main.py — the entry point; builds the CustomTkinter GUI, wires up the file picker and job-description input, runs the analysis pipeline on a background thread, and renders the deterministic + AI results
• analyzer.py — everything that doesn't need the network: file parsing (PDF/DOCX/TXT/image), text cleanup, contact/skill/section extraction, scoring, and suggestion generation. Fully usable on its own, without any API key
• ai_advisor.py — the Groq integration; builds the TR/EN system prompts, sends the resume text + analyzer.py's extracted facts, and parses the model's JSON response into an AIInsights object. Kept separate on purpose so the deterministic engine keeps working even if this fails
• i18n.py — a flat dict-based string table for the two UI languages (tr/en), looked up through a single t(lang, key) helper

Secrets (the Groq API key) are read from environment variables via python-dotenv — see Usage below.

📁 Project Structure

Smart_Resume_Analyzer/
├── main.py            # Entry point - CustomTkinter GUI & analysis pipeline
├── analyzer.py         # File parsing + deterministic NLP scoring engine
├── ai_advisor.py       # Groq LLM integration (prompts, request, response parsing)
├── i18n.py             # TR/EN UI string table
├── img/                # Screenshots used in this README
│   ├── cv1.jpg
│   ├── cv1analiz.png
│   ├── cv2.png
│   └── cv2analiz.png
├── .env.example        # Template for GROQ_API_KEY / GROQ_MODEL
├── .gitignore
├── requirements.txt
├── LICENSE
└── README.md

🚀 Usage

1. Clone the repository

   git clone https://github.com/<your-username>/Smart_Resume_Analyzer.git
   cd Smart_Resume_Analyzer

2. Create a virtual environment and install dependencies (Python 3.10+ recommended)

   python -m venv .venv
   .venv\Scripts\activate        # Windows
   pip install -r requirements.txt
   python -m spacy download en_core_web_sm

3. Install Tesseract OCR so image (PNG/JPG/JPEG) resumes can be read — the pytesseract package is only a Python wrapper, it does not install the OCR engine itself:
   • Windows: install via UB-Mannheim's Tesseract build and add the install folder (e.g. C:\Program Files\Tesseract-OCR) to your PATH
   • Check the Turkish language pack during setup if you want to OCR Turkish text; otherwise the app automatically falls back to English-only OCR
4. Copy .env.example to .env and set your own free Groq API key from console.groq.com:

   copy .env.example .env

   The app still works without a key — the deterministic score and suggestions are shown, only the AI card is disabled.
5. Run it

   python main.py

   Pick a resume file from the sidebar, optionally paste a target job description, and click "Analyze".

Programmatic usage (deterministic engine only, no GUI):

from analyzer import analyze_file

result = analyze_file("resume.pdf")
print(result.report())      # human-readable text report
print(result.to_dict())     # structured data for JSON/UI

🤝 Contributing

1. Fork the repository
2. Create a new branch
3. Commit your changes
4. Push the branch
5. Open a pull request

📝 License

This project is licensed under the MIT License.

🇹🇷 Türkçe

---

📖 Hakkında

AI Resume Analyzer, CV'leri (PDF, DOCX, TXT ve taranmış/fotoğraflanmış PNG/JPG dosyalarını dahi) modern bir CustomTkinter arayüzü üzerinden analiz eden bir masaüstü uygulamasıdır. CV, deterministik bir NLP puanlama motorundan (analyzer.py) geçirilir; bunun üzerine, çıkarılan veriler ve ham metin bir Groq LLM'e (ai_advisor.py) gönderilir ve model otomatik bir işe alım ön elemesi gibi davranarak işe alım kararı, ayrıntılı gerekçe, güçlü yönler, risk faktörleri ve eksik bilgiler üretir. Arayüzün tamamı Türkçe/İngilizce iki dillidir ve anında dil değiştirir.

✨ Özellikler

Deterministik analiz motoru (analyzer.py)

• PDF (pdfminer.six → PyPDF2 yedeği → taranmış/font sorunlu PDF'ler için OCR yedeği), DOCX (tablolar dahil), TXT ve PNG/JPG/JPEG (Tesseract OCR, Türkçe + İngilizce) okur
• Mojibake'i (UTF-8 metnin CP1252/Latin-1 olarak yanlış çözülmesi) otomatik onarır ve Unicode'u normalize eder; böylece Türkçe karakterler her zaman doğru görünür
• İletişim bilgisi çıkarma: e-posta, telefon, LinkedIn, GitHub, diğer portföy bağlantıları
• 6 kategoride kategorize yetenek eşleştirme: programlama dilleri, web/frameworkler, veritabanları, bulut/DevOps, veri bilimi/AI, kişisel beceriler
• Bölüm kapsama tespiti (İletişim, Özet, Deneyim, Eğitim, Yetenekler, Projeler, Sertifikalar, Diller) ve Türkiye'ye özgü ek bilgiler (ehliyet, askerlik durumu, referanslar)
• Tarih aralıklarından deneyim yılı tahmini, eğitim seviyesi tespiti, eylem fiili ve ölçülebilir başarı analizi
• Opsiyonel iş ilanı karşılaştırması — anahtar kelime eşleşme yüzdesi ve eksik yetenekler
• Ağırlıklı 0-100 puan, harf notu ve somut, aksiyon alınabilir öneriler

AI işe alım danışmanı (ai_advisor.py)

• CV metnini ve çıkarılan verileri Groq'a gönderir, modelden bir kariyer koçu değil, işveren tarafındaki bir işe alım uzmanı gibi davranmasını ister
• Yapılandırılmış bir işe alım kararı, gerekçe, eğitim/deneyim değerlendirmeleri, güçlü yönler, risk faktörleri, eksik bilgiler, uygun pozisyonlar ve (iş ilanı verildiyse) bir iş uygunluk yüzdesi döndürür
• Alan bazlı: teknik olmayan adayları (örn. öğretmen, hemşire) GitHub/portföy linki eksikliği yüzünden asla olumsuz değerlendirmez
• Cinsiyete duyarlı: kadın olduğu anlaşılan adaylar için Türkiye askerlik durumunu hiçbir şekilde gündeme getirmez
• Tamamen dayanıklı — GROQ_API_KEY yoksa veya API çağrısı başarısız olursa uygulama çökmez; deterministik sonuçlar gösterilmeye devam eder, sadece AI kartı durumu bildirir

Modern arayüz (main.py)

• CustomTkinter tabanlı, açık/koyu/sistem görünüm modlarına sahip kart tarzı tasarım
• Anında yeniden çizen tam Türkçe/İngilizce arayüz geçişi (i18n.py)
• Dosya seçici + opsiyonel iş ilanı metin kutusu, analiz arka planda bir thread'de çalışır, arayüz hiç donmaz
• Skor kartı, renkli yetenek etiketleri, bölüm kontrol listesi, iş ilanı eşleşme çubuğu ve güçlü yön/risk/eksik bilgi listeleriyle birlikte özel bir AI karar bandı

🛠️ Kullanılan Teknolojiler

• Python 3 — ana dil
• CustomTkinter — modern masaüstü arayüzü
• spaCy — tokenizasyon, lemmatizasyon, stopword filtreleme, cümle bölümleme
• pdfminer.six + PyPDF2 — PDF metin çıkarma (birincil + yedek)
• PyMuPDF (fitz) — OCR yedek yolu için PDF sayfalarını görsele dönüştürür
• python-docx — DOCX metin/tablo çıkarma
• pytesseract + Pillow (Tesseract OCR) — taranmış/fotoğraflanmış CV'lerden metin çıkarma
• Groq API — LLM tabanlı işe alım geri bildirimi
• python-dotenv — gizli bilgileri (API anahtarı) ortam değişkenlerinden yükler

📸 Ekran Görüntüleri

CV	CV Analizi

Solda: uygulamaya verilen örnek bir CV. Sağda: aynı CV için üretilen puan, AI işe alım kararı, güçlü yönler, riskler ve eksik bilgiler.

⚙️ Nasıl Çalışıyor

Proje, alt paketleri olmayan, düz dört modüllük bir Python yapısı ve bir metin tablosundan oluşur:

• main.py — giriş noktası; CustomTkinter arayüzünü kurar, dosya seçici ve iş ilanı girişini bağlar, analiz akışını arka planda bir thread'de çalıştırır, deterministik + AI sonuçlarını gösterir
• analyzer.py — ağ bağlantısı gerektirmeyen her şey: dosya okuma (PDF/DOCX/TXT/görsel), metin temizleme, iletişim/yetenek/bölüm çıkarma, puanlama ve öneri üretimi. API anahtarı olmadan da tek başına kullanılabilir
• ai_advisor.py — Groq entegrasyonu; TR/EN sistem prompt'larını oluşturur, CV metnini + analyzer.py'nin çıkardığı verileri gönderir ve modelin JSON yanıtını bir AIInsights nesnesine ayrıştırır. Bu, deterministik motorun bu adım başarısız olsa bile çalışmaya devam etmesi için bilinçli olarak ayrı tutulmuştur
• i18n.py — iki arayüz dili (tr/en) için düz bir dict tabanlı metin tablosu, tek bir t(lang, key) yardımcı fonksiyonu üzerinden okunur

Gizli bilgiler (Groq API anahtarı) python-dotenv ile ortam değişkenlerinden okunur — aşağıdaki Kullanım bölümüne bakın.

📁 Proje Yapısı

Smart_Resume_Analyzer/
├── main.py            # Giriş noktası - CustomTkinter arayüzü & analiz akışı
├── analyzer.py         # Dosya okuma + deterministik NLP puanlama motoru
├── ai_advisor.py       # Groq LLM entegrasyonu (prompt'lar, istek, yanıt ayrıştırma)
├── i18n.py             # TR/EN arayüz metin tablosu
├── img/                # Bu README'de kullanılan ekran görüntüleri
│   ├── cv1.jpg
│   ├── cv1analiz.png
│   ├── cv2.png
│   └── cv2analiz.png
├── .env.example        # GROQ_API_KEY / GROQ_MODEL için şablon
├── .gitignore
├── requirements.txt
├── LICENSE
└── README.md

🚀 Kullanım

1. Depoyu klonlayın

   git clone https://github.com/<kullanici-adiniz>/Smart_Resume_Analyzer.git
   cd Smart_Resume_Analyzer

2. Sanal ortam oluşturup bağımlılıkları kurun (Python 3.10+ önerilir)

   python -m venv .venv
   .venv\Scripts\activate        # Windows
   pip install -r requirements.txt
   python -m spacy download en_core_web_sm

3. Görsel (PNG/JPG/JPEG) CV'leri okuyabilmek için Tesseract OCR'ı kurun — pytesseract paketi sadece Python arayüzüdür, OCR motorunun kendisini kurmaz:
   • Windows: UB-Mannheim Tesseract kurulumu ile kurup, kurulum dizinini (örn. C:\Program Files\Tesseract-OCR) PATH'e ekleyin
   • Türkçe metinleri OCR'layabilmek için kurulumda Türkçe dil paketini de işaretleyin; işaretlenmezse uygulama otomatik olarak sadece İngilizce OCR'a düşer
4. .env.example dosyasını .env olarak kopyalayıp console.groq.com üzerinden aldığınız ücretsiz Groq API anahtarınızı girin:

   copy .env.example .env

   Anahtar olmadan da uygulama çalışır — deterministik puan ve öneriler gösterilir, sadece AI kartı devre dışı kalır.
5. Çalıştırın

   python main.py

   Soldaki panelden bir CV dosyası seçin, isteğe bağlı olarak bir hedef iş ilanı metni girin ve "Analiz Et" butonuna tıklayın.

Programatik kullanım (yalnızca deterministik motor, arayüz olmadan):

from analyzer import analyze_file

result = analyze_file("cv.pdf")
print(result.report())      # okunabilir metin raporu
print(result.to_dict())     # JSON/UI için yapılandırılmış veri

🤝 Katkıda Bulunma

1. Projeyi fork'layın
2. Yeni bir branch oluşturun
3. Değişikliklerinizi commit edin
4. Branch'i push edin
5. Pull request oluşturun

📝 Lisans

Bu proje MIT Lisansı ile lisanslanmıştır.