SHL Assessment Recommendation System

A production-ready recommendation engine that matches job descriptions to SHL assessments using Hybrid Vector Search and LLM-based Reranking.

Table of Contents

• System Architecture
• Key Features
• Tech Stack
• Installation & Setup
• Usage
• Evaluation & Metrics
• Engineering Decisions
• License

System Architecture

The system follows a Two-Stage Retrieval Pipeline to balance speed and accuracy:

1. Candidate Generation (Retrieval): Uses ChromaDB and sentence-transformers to perform semantic search across 377+ unique assessments.

2. Scoring & Ranking (Reranking): Employs the Gemini (gemini-2.5-flash) LLM to evaluate the top candidates against specific job nuances (e.g., time limits, seniority).

Key Features

• Semantic Matching: Understands the context of a Job Description rather than just matching keywords.

• Robust API: FastAPI backend with Pydantic validation for seamless integration.

• Intuitive UI: Interactive Streamlit dashboard for real-time testing and assessment discovery.

• Rate-Limit Optimization: Implemented request throttling and graceful fallbacks for stable batch processing.

Tech Stack

• Language: Python 3.9+

• Vector DB: ChromaDB

• Embeddings: all-MiniLM-L6-v2 (Sentence-Transformers)

• LLM: Google Gemini (gemini-2.5-flash)

• API: FastAPI & Uvicorn

• Frontend: Streamlit

Installation & Setup

1. Clone & Environment

git clone https://github.com/yourusername/SHL_Recommendation_System.git
cd SHL_Recommendation_System
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

2. Dependencies

pip install -r requirements.txt

3. API Configuration

Create a .env file in the root directory:

GEMINI_API_KEY=your_key_here

🛠 Usage

Rebuilding the Vector Store

If you need to re-index the data (deduplication is handled automatically):

python src/engine/vector_store.py

Running the API (Port 8000)

uvicorn src.api.main:app --host 0.0.0.0 --port 8000

• Health Check: GET /health

• Recommend: POST /recommend (Body: {"query": "Java Developer"})

Running the UI (Port 8501)

streamlit run src/ui/streamlit_app.py

Evaluation & Metrics

The system is optimized for Mean Recall@10.

To generate the final submission CSV for the 9 test queries:

python evaluations/generate_submission.py

• Format: Follows Appendix 3 (Repeated Query, Assessment_url).

• Constraint: Ensures a minimum of 5 and maximum of 10 recommendations per query.

Engineering Decisions

• Data Deduplication: The database was purged and rebuilt to remove duplicate entries, increasing recommendation diversity and Recall@10 accuracy.

• API Fallback: Implemented a fallback to raw vector scores when LLM rate limits are hit, ensuring 100% system availability.

License

This project is licensed under the MIT License.