SHL Assessment Recommendation System

This project is a recommendation system that suggests relevant SHL assessments based on a job description or free-text query.

The goal is to take a user query (for example, a job description for a Java Developer or Data Analyst) and return the most suitable SHL assessment URLs in ranked order.

The system was built as part of an assessment task and includes:

• Model training and evaluation
• Hybrid retrieval pipeline
• Performance optimization
• API deployment
• Web frontend
• Test set prediction generation

---

🔍 Problem Overview

Given:

• A catalog of SHL assessments (name, URL, description)
• A labeled training dataset (query → relevant assessment URLs)

Build a system that:

1. Recommends top 10 relevant assessments for any input query
2. Maximizes Recall@10 on the training set
3. Exposes a public API endpoint
4. Provides a simple web interface
5. Generates predictions for the unlabeled test set

---

🧠 Approach

1. Data Processing

• Cleaned and normalized catalog text
• Combined assessment name and description
• Prepared slug mappings for evaluation

2. Hybrid Retrieval System

The final pipeline uses a combination of:

• Dense embeddings (Sentence Transformers)
• FAISS similarity search
• BM25 keyword matching
• Score fusion for ranking
• Training-based slug boosting

Pure semantic similarity was not sufficient, so lexical matching was combined with embeddings to improve recall.

---

📈 Evaluation

Metric used: Recall@10

Initial performance (baseline embedding only):

• Very low recall

After introducing hybrid retrieval and boosting:

• Mean Recall@10 improved significantly (~0.70+)

Evaluation script is included in the repository.

---

🏗️ Project Structure

src/
  recommender/
    pipeline.py
    training_boost.py
    ...

app.py
requirements.txt
generate_test_predictions.py
evaluate.py

• pipeline.py → Main recommendation logic
• app.py → FastAPI endpoint
• evaluate.py → Recall@10 evaluation
• generate_test_predictions.py → Creates final submission CSV

---

🚀 Running Locally

1. Install dependencies

pip install -r requirements.txt

2. Run API

uvicorn app:app --reload

API will be available at:

http://127.0.0.1:8000/docs

Test the /recommend endpoint using Swagger UI.

---

🌐 Deployment

The API is deployed on Render and exposes a POST endpoint:

/recommend

Request format:

{
  "query": "Java developer test"
}

Response:

{
  "recommendations": [
"https://...",
"https://..."
  ]
}

A simple web frontend is also deployed to test the system interactively.

---

📄 Test Set Predictions

Final predictions for the unlabeled dataset are generated as a CSV file with:

• Column 1: query
• Column 2: predictions (comma-separated URLs)

Format matches the specification in the assignment PDF.

---