An intelligent candidate screening chatbot built for TalentScout, a fictional recruitment agency. The chatbot collects candidate information through a conversational interface and generates tailored technical interview questions based on the candidate's declared tech stack.
Built as an AI / ML Intern assignment project.
| Feature | Description |
|---|---|
| Conversational UI | Clean Streamlit chat interface with gradient header and modern styling |
| Sequential Info Collection | Gathers name, email, phone, experience, desired role, location, and tech stack |
| Input Validation | Regex‑based email & phone validation, numeric experience check |
| AI Question Generation | Uses Google Gemini (free tier) to generate 3–5 interview questions per technology |
| Difficulty Tags | Questions tagged as Basic, Intermediate, or Advanced |
| Sentiment Analysis | Real‑time keyword‑based sentiment badge in the sidebar |
| State Machine | Robust finite‑state machine drives the conversation flow |
| Data Persistence | Candidate records saved to data/candidates.json |
| Fallback Handling | Graceful responses for unclear or off‑topic input |
| Exit Detection | Recognises exit / quit / done / bye to end the session |
talentscout-ai-assistant/
│
├── app.py ← Streamlit frontend (UI, session state, routing)
├── chatbot.py ← Core conversation engine (state machine, LLM calls)
├── prompts.py ← All LLM prompt templates (centralised)
├── utils.py ← Validators, data store, sentiment, helpers
├── requirements.txt ← Python dependencies
├── README.md ← This file
└── data/
└── candidates.json ← Persisted candidate records
User Input
│
▼
app.py (Streamlit) ──▶ chatbot.py (State Machine)
│ │
│ ├── validates via utils.py
│ ├── generates prompts from prompts.py
│ └── calls Google Gemini API
│ │
▼ ▼
Chat Display data/candidates.json
- Python 3.9 or later
- A Google Gemini API key (get one free here)
# 1. Clone the repository
git clone https://github.com/<your-username>/talentscout-ai-assistant.git
cd talentscout-ai-assistant
# 2. Create and activate a virtual environment (recommended)
python -m venv venv
# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Configure your API key
# Create a file called .env in the project root:
echo GOOGLE_API_KEY=your-gemini-key-here > .envstreamlit run app.pyThe app will open in your default browser at http://localhost:8501.
All prompts live in prompts.py and follow these design principles:
| Principle | How it's applied |
|---|---|
| Role anchoring | SYSTEM_PROMPT keeps the model in a professional hiring‑assistant persona at all times |
| Structured output | TECH_QUESTION_PROMPT prescribes Markdown formatting and difficulty tags so the output is consistent and parseable |
| Constraint injection | Prompts explicitly say "Do NOT provide answers" and "Stay within hiring context" to reduce hallucination and off‑topic drift |
| Template variables | {name}, {tech_stack}, {message} placeholders decouple prompt logic from data, making prompts reusable |
| Single‑responsibility | Each prompt handles exactly one task (greeting, validation error, question generation, sentiment) for clarity and maintainability |
- Information Gathering — Static templates (no LLM call needed) that guide the candidate through each field.
- Tech Stack Analysis — A single, detailed LLM prompt that takes the comma‑separated tech list and outputs structured questions.
- Sentiment Analysis — A minimal one‑shot prompt asking the model to classify a message as Positive / Neutral / Negative.
| Challenge | Solution |
|---|---|
| Keeping the LLM on‑topic | Strong system prompt with explicit constraints; fallback mechanism redirects off‑topic messages |
| Input validation | Dedicated regex validators in utils.py with clear error messages; re‑prompts until valid |
| State management | Finite‑state machine in chatbot.py integrated with Streamlit's session_state |
| Consistent question quality | Detailed formatting instructions and difficulty tags in the prompt template |
| Data persistence | Atomic read‑write cycle in save_candidate() with JSON decode error recovery |
- Database backend — Replace JSON file with SQLite or PostgreSQL for concurrent access.
- Multilingual support — Detect candidate language and respond accordingly.
- Resume parsing — Accept PDF/DOCX uploads and auto‑fill candidate fields.
- Admin dashboard — Streamlit multi‑page app for recruiters to review candidates.
- Answer evaluation — Let candidates answer the generated questions and have the LLM grade them.
- Authentication — Add login for recruiters / candidates.
- Deployment — Dockerise and deploy to Streamlit Cloud or AWS.
This project is created for educational purposes as part of an AI/ML internship assignment.