Guna522/conversational-recommendation-agent

Conversational Recommendation Agent

Overview

This project is a conversational AI recommendation system built using FastAPI, hybrid retrieval, and semantic search.

The system recommends relevant evaluations based on hiring requirements provided conversationally by the user.

The agent supports:

• —conversational clarification
• —recommendation refinement
• —comparison requests
• —off-topic refusal handling
• —stateless conversation processing

The system uses hybrid retrieval combining:

• —semantic search using FAISS embeddings
• —keyword retrieval using BM25

The backend is built using FastAPI.

Features

• —Hybrid retrieval using FAISS and BM25
• —Conversational recommendation flow
• —Stateless conversation handling
• —Clarification question support
• —Recommendation refinement support
• —Comparison request handling
• —Prompt injection and off-topic refusal logic
• —FastAPI REST API
• —Swagger API documentation

Architecture

User Query
    ↓
Conversation State Extraction
    ↓
Hybrid Retrieval Engine
    ├── FAISS Semantic Search
    └── BM25 Keyword Search
    ↓
Result Reranking
    ↓
Recommendation Generation
    ↓
FastAPI Response

Tech Stack

Project Structure

shl-assessment-agent/
│
├── app/
│   ├── main.py
│   │
│   ├── services/
│   │   ├── retrieval.py
│   │   ├── state_builder.py
│   │   └── chat_engine.py
│   │
│   ├── models/
│   │   └── schemas.py
│   │
│   └── data/
│       ├── processed_catalog.json
│       ├── faiss.index
│       ├── embeddings.npy
│       └── bm25.pkl
│
├── scripts/
│   ├── preprocess_catalog.py
│   ├── build_embeddings.py
│   ├── build_bm25.py
│   ├── test_retrieval.py
│   ├── test_bm25.py
│   ├── test_hybrid.py
│   ├── test_state.py
│   └── test_chat.py
│
├── requirements.txt
├── README.md
└── .gitignore

Installation

1. Clone the repository

git clone <your-repository-url>
cd shl-assessment-agent

2. Create virtual environment

python -m venv venv

3. Activate virtual environment

Windows

venv\Scripts\activate

4. Install dependencies

pip install -r requirements.txt

5. Run the application

uvicorn app.main:app --reload

API Endpoints

Health Check

GET /health

Response

{
  "status": "ok"
}

Chat Endpoint

POST /chat

Request

{
  "messages": [
    {
      "role": "user",
      "content": "I need assessments for a Java backend developer"
    }
  ]
}

Response

{
  "reply": "Here are 5 recommended assessments.",
  "recommendations": [
    {
      "name": "Java 8 (New)",
      "url": "https://example.com",
      "test_type": "Knowledge & Skills"
    }
  ],
  "end_of_conversation": false
}

Retrieval Pipeline

The recommendation engine uses hybrid retrieval.

Semantic Search

• —SentenceTransformer embeddings
• —FAISS vector similarity search
• —Semantic understanding of queries

Keyword Search

• —BM25 ranking
• —Exact keyword matching
• —Skill and technology matching

Hybrid Ranking

Results from both systems are combined and reranked for better recommendation quality.

Conversation Handling

The system reconstructs conversation state from the full message history for every request.

Extracted information includes:

• —role
• —skills
• —seniority
• —personality requirements
• —cognitive requirements

The API is fully stateless.

Supported Behaviors

Clarification

The agent asks follow-up questions when insufficient information is available.

Refinement

Users can modify requirements mid-conversation.

Example:

User: Need Java backend assessments
User: Also include personality tests

Comparison

The agent supports comparison-style queries.

Example:

Difference between Java 8 and Core Java

Refusal Logic

The system rejects:

• —prompt injection attempts
• —legal advice requests
• —medical advice requests
• —unrelated requests

Swagger Documentation

After running the application:

http://127.0.0.1:8000/docs

Future Improvements

• —LLM-powered comparison generation
• —Better reranking strategies
• —Advanced query expansion
• —Improved personality assessment matching
• —Conversation memory optimization
• —Evaluation benchmarking