SHL Assessment Recommender

A conversational AI agent built with FastAPI that helps hiring managers and recruiters navigate the SHL product catalog to find the right individual test solutions. It takes users from a vague intent to a grounded shortlist of SHL assessments through dialogue.

🚀 Live Demo

Deployed API: https://shl-recommender.onrender.com

Hosted on Render (free tier). The first request may take ~30–60 seconds as the service spins up from sleep.

Endpoint	Method	Description
/	GET	Service info
/health	GET	Health check → {"status": "ok"}
/chat	POST	Conversational recommendation endpoint

Quick Test

# Health check
curl https://shl-recommender.onrender.com/health

# Chat — single-turn recommendation
curl -X POST https://shl-recommender.onrender.com/chat \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "I need to hire a Java developer"}]}'

📖 Overview

This service exposes a stateless POST /chat endpoint that processes conversation history, retrieves relevant assessments using a FAISS vector index, and returns structured recommendations generated by a Groq LLaMA model. It strictly adheres to SHL catalog constraints and prevents hallucinations.

✨ Features

• Semantic + Keyword Retrieval: Uses sentence-transformers (all-MiniLM-L6-v2) and FAISS for efficient, high-recall retrieval with keyword boosting for precision.
• Conversational Handling: Clarifies vague queries, recommends specific assessments, refines shortlists based on updated constraints, and compares assessments side-by-side.
• Strict Guardrails: Refuses off-topic questions (e.g., prompt injection, salary info) and verifies every recommended URL against the scraped catalog.
• Stateless API: Follows the REST pattern — takes the full conversation history in every request with no server-side session state.
• Turn Limit Enforcement: Automatically forces recommendations by turn 6+ to ensure conversations converge.

🛠️ Tech Stack

Layer	Technology
Web Framework	FastAPI + Uvicorn
LLM Provider	Groq (llama-3.3-70b-versatile)
Embeddings	SentenceTransformers (all-MiniLM-L6-v2)
Vector Store	FAISS-CPU
Scraping	BeautifulSoup, Requests, Playwright
Deployment	Render (free tier)

📁 Project Structure

shl-recommender/
├── app/
│   ├── main.py          # FastAPI app, endpoints, request/response models
│   ├── agent.py         # LLM orchestration, prompt construction, post-processing
│   └── retrieval.py     # FAISS index, semantic search, keyword boosting
├── catalog.json         # Scraped SHL assessment catalog (377 items)
├── test_agent.py        # 6-scenario conversational test suite
├── requirements.txt     # Python dependencies
├── render.yaml          # Render deployment config
├── Procfile             # Heroku/Railway deployment
├── Approach_Document.md # Detailed design & evaluation document
└── .env                 # Local environment variables (not committed)

📋 Prerequisites

• Python 3.10+
• A Groq API Key

⚙️ Local Setup

1. Clone the repository:

   git clone https://github.com/wildtigress/Conversational-SHL-Assessment-Recommender.git
   cd Conversational-SHL-Assessment-Recommender/shl-recommender

2. Create and activate a virtual environment:

   python -m venv venv
   # On Windows:
   venv\Scripts\activate
   # On macOS/Linux:
   source venv/bin/activate

3. Install dependencies:

   pip install torch --index-url https://download.pytorch.org/whl/cpu
   pip install -r requirements.txt

4. Environment Variables: Create a .env file in the root directory:

   GROQ_API_KEY=your_groq_api_key_here

5. Run the server:

   python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

📡 API Reference

GET /health

Returns 200 OK when the service is running.

{ "status": "ok" }

POST /chat

Accepts a JSON payload with messages (the conversation history) and returns a structured response.

Request:

{
  "messages": [
    { "role": "user", "content": "I am hiring a Java developer" }
  ]
}

Response:

{
  "reply": "Got it. What seniority level are you looking for?",
  "recommendations": [],
  "end_of_conversation": false
}

Response (with recommendations):

{
  "reply": "Based on your requirements, here are the recommended assessments:",
  "recommendations": [
    {
      "name": "Java Programming Assessment",
      "url": "https://www.shl.com/solutions/...",
      "test_type": "Knowledge & Skills"
    }
  ],
  "end_of_conversation": true
}

🧪 Testing

Run the included test suite to verify all agent behaviors:

python test_agent.py

This runs 6 multi-turn conversational traces covering:

1. Vague query → clarification
2. Job description → immediate recommendation
3. Mid-conversation refinement
4. Assessment comparison
5. Off-topic refusal
6. Prompt injection rejection

🚢 Deployment

This application is deployed on Render using the included render.yaml.

Platform	Config File	Notes
Render	render.yaml	Free tier, auto-deploy enabled
Heroku / Railway	Procfile	Add GROQ_API_KEY to env vars

Important: Add GROQ_API_KEY to your environment variables on whichever deployment platform you use.

📄 Documentation

• Approach Document — Detailed write-up covering design choices, retrieval setup, prompt engineering, evaluation results, and lessons learned.