README.md

metadata

title: Alture AI — Job Intelligence & Explainable ATS Engine
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: mit
short_description: Hybrid NLP Job Recommendation & ATS Engine

Alture AI — Hybrid NLP-Based Job Recommendation and Resume–Job Matching System

📌 Problem Statement

Most job-search and ATS (Applicant Tracking System) tools match resumes to jobs by simply looking for matching keywords. This project builds a smarter matching system that understands the actual meaning behind a resume and a job description — not just the words used — and gives a clear, explainable match score.

The system combines three signal types:

1. Semantic Similarity — Sentence-BERT embeddings capture meaning beyond keywords
2. Skill Overlap Extraction — spaCy NER + custom skill dictionary identifies matched/missing skills
3. Structured Features — Text length, keyword density, and other engineered features

A gradient-boosted meta-learner (XGBoost) combines these signals to predict ATS compatibility scores, outperforming any single approach alone.

📊 Dataset

• Name: Resume-ATS Score Dataset v1 (English)
• Source: Hugging Face — 0xnbk/resume-ats-score-v1-en
• Size: ~6,400 resume–job description pairs (5,100 train / 1,300 validation)
• Features: Resume text, Job Description text, ATS compatibility score (18.3–90.7), Fit label (No Fit / Potential Fit / Good Fit)
• Target Variable: ATS compatibility score (continuous)

Note: The dataset is automatically downloaded when you run the notebooks. No manual download needed.

🏗️ Project Structure

Project-Folder/
├── README.md                    # This file
├── requirements.txt             # Python dependencies
├── .gitignore                   # Git ignore rules
│
├── notebooks/                   # Jupyter analysis notebook with all outputs
│   └── Capstone_Full_Pipeline.ipynb # End-to-end executed notebook (Parts 1-9)
│
├── src/                         # Reusable source modules
│   ├── __init__.py
│   ├── data_loader.py           # Dataset downloading & loading
│   ├── preprocessing.py         # Text cleaning & feature engineering
│   ├── feature_extraction.py    # TF-IDF, SBERT, skill extraction
│   ├── models.py                # Model training & evaluation utilities
│   └── utils.py                 # Helper functions
│
├── deployment/                  # Production Full-Stack Deployment
│   ├── backend/                 # FastAPI REST Microservice
│   │   ├── main.py              # Application entrypoint & static mounting
│   │   ├── matcher_service.py   # Hybrid NLP & 500+ Skill Ontology engine
│   │   ├── schemas.py           # Pydantic V2 request/response schemas
│   │   └── sample_data.py       # Global tech job postings & candidate personas
│   └── frontend/                # Modern Modular React UI
│       ├── index.html           # HTML5 shell
│       ├── app.js               # React 18 state & component architecture
│       └── styles.css           # Modern dark SaaS design system
│
├── models/                      # Saved trained models
│   └── (auto-generated .joblib files)
│
├── data/                        # Cached dataset files
│   └── (auto-downloaded)
│
├── outputs/                     # Generated figures and results
│   └── figures/                 # EDA and evaluation plots
│
└── paper/                       # IEEE LaTeX research paper
    ├── main.tex                 # LaTeX source
    ├── references.bib           # Bibliography
    ├── figures/                 # Paper figures
    └── main.pdf                 # Compiled PDF

🚀 Setup & Installation

Prerequisites

• Python 3.9 or higher
• pip package manager

Step 1: Clone the Repository

git clone https://github.com/Ahmad-Mustafa-Iqbal/Alture-AI.git
cd Alture-AI

Step 2: Install Dependencies

pip install -r requirements.txt
python -m spacy download en_core_web_sm

Step 3: Run the Notebook (Optional for inspection / re-training)

Open and run notebooks/Capstone_Full_Pipeline.ipynb in Jupyter Lab, VS Code, or Google Colab. All cells are pre-executed with visible outputs and visualizations.

Step 4: Launch Production FastAPI Backend & React UI

# Launch the server (Serves both the REST API and the React Frontend on Port 8000)
python -m deployment.backend.main

Or with Uvicorn:

uvicorn deployment.backend.main:app --reload --port 8000

• 🌐 Interactive Web UI: Open http://localhost:8000 in your browser.
• 📖 Interactive OpenAPI Swagger Docs: Open http://localhost:8000/docs.

📈 Model Performance & Results (Alture AI v2.0 Benchmark)

Model	Architecture Type	MAE ↓	RMSE ↓	R² ↑	Precision@Top25% ↑	F1-Score ↑	nDCG@10 ↑
Baseline 1: TF-IDF + Ridge	Lexical Linear	17.55	21.40	0.265	0.674	0.611	0.670
Baseline 2: TF-IDF + Random Forest	Lexical Ensemble	20.53	24.07	0.070	0.444	0.090	0.490
Baseline 3: SBERT + Ridge	Dense Semantic	19.37	22.75	0.169	0.587	0.263	0.860
Proposed: Cross-Encoder + XGBoost	Hybrid Attention	17.15	20.79	0.306	0.672	0.524	0.943
Proposed: Cross-Encoder + LightGBM	Hybrid Fast Tree	17.17	20.63	0.316	0.688	0.529	0.905
Proposed: Cross-Encoder + CatBoost	Hybrid Categorical	18.54	21.84	0.234	0.632	0.378	0.964
🏆 Proposed: Stacking Super-Ensemble	Multi-Modal Blend	17.32	20.72	0.311	0.709 (71%)	0.502	0.947 (95%)

Note: Evaluated on out-of-sample holdout test split (1,275 samples).

📏 Evaluation Metrics

• MAE (Mean Absolute Error) — Average prediction gap
• RMSE (Root Mean Squared Error) — Penalizes large errors
• R² Score — Variance explained by the model
• Precision / Recall / F1-Score — Classification performance on fit categories
• nDCG@K — Ranking quality for recommendation

🛠️ Technologies Used

• Python 3.9+
• FastAPI & Uvicorn — Production asynchronous REST API
• React 18 — Component-driven interactive web interface
• Pydantic V2 — Data validation and schemas
• scikit-learn — TF-IDF, linear models, ensemble metrics
• sentence-transformers — Sentence-BERT (all-MiniLM-L6-v2) & Cross-Encoders
• spaCy — Named entity recognition & skill extraction ontology
• XGBoost / LightGBM / CatBoost — Gradient boosted meta-learners
• matplotlib / seaborn — Statistical evaluation visualization
• datasets (HuggingFace) — Ingestion of resume-ATS corpus
• matplotlib / seaborn / plotly — Visualization
• datasets (HuggingFace) — Dataset loading

📝 Research Paper

The IEEE-format research paper is located in the paper/ folder:

• paper/main.tex — LaTeX source file
• paper/main.pdf — Compiled PDF
• paper/references.bib — Bibliography

👤 Author

Ahmad — Internship Capstone Project (Week 7–8)

📄 License

This project is for educational purposes as part of an internship program.