TalentScout : Intelligent Hiring Assistant

An AI-powered chatbot that conducts initial candidate screenings for TalentScout, a technology recruitment agency. Built with Streamlit and Llama 3 via Groq, the assistant collects candidate information and generates tailored technical interview questions based on the candidate's declared tech stack.

Overview

TalentScout's Hiring Assistant ("Scout") automates the initial phase of candidate screening by:

Greeting the candidate and explaining the process
Collecting essential information (name, email, phone, experience, desired position, location, tech stack)
Generating 3-5 tailored technical questions per technology in the candidate's stack
Evaluating responses with professional, encouraging feedback
Concluding the session with a summary and next-steps information

The chatbot maintains full conversation context, validates inputs, handles edge cases gracefully, and stores session data securely.

Features

Core

Conversational Screening — Natural, step-by-step information gathering
Dynamic Technical Questions — Generated based on candidate's tech stack & experience level
Input Validation — Email, phone, and field-specific validation with gentle correction prompts
Context Awareness — Full conversation history maintained for coherent follow-ups
Fallback Handling — Graceful redirect for off-topic or unexpected inputs
Exit Detection — Keywords like "bye", "quit", "exit" trigger graceful conclusion
Session Persistence — Candidate data saved as JSON for recruiter review

Bonus

Sentiment Analysis — Real-time candidate mood tracking displayed in the sidebar
Multilingual Support — Auto-detects non-English input and provides bilingual responses
Premium UI — Custom dark theme with glassmorphism, animations, and gradient accents

Architecture

graph TD
    A["👤 Candidate"] -->|interacts| B["Streamlit UI"]
    B -->|user message| C["Conversation Manager"]
    C -->|builds prompt| D["Prompt Engine"]
    D -->|API call| E["Llama 3 (Groq)"]
    E -->|response| C
    C -->|updates| F["Session State"]
    F -->|renders| B
    C -->|stores| G["Data Store (JSON)"]

    subgraph "Bonus Modules"
        H["Sentiment Analyzer"]
        I["Multilingual Detector"]
    end
    C --> H
    C --> I

Conversation State Machine

The conversation progresses through these ordered phases:

GREETING → NAME → EMAIL → PHONE → EXPERIENCE → POSITION → LOCATION → TECH STACK → QUESTIONS → ANSWERS → FAREWELL

Each phase has:

A tailored prompt template
Input validation rules
Automatic phase transition on valid input
Fallback handling for invalid input

Installation

Prerequisites

Python 3.10+
A Groq API key (Get one free here)

Steps

Clone the repository

git clone https://github.com/rishii100/talentscout.git
cd talentscout

Create a virtual environment (recommended)

python -m venv venv
source venv/bin/activate

Install dependencies
```
pip install -r requirements.txt
```
Set up your API key
```
cp .env.example .env
```
Run the application
```
streamlit run app.py
```
Open in browser — Navigate to http://localhost:8501

Usage Guide

Start — The assistant greets you and begins the screening
Provide Information — Answer each question one at a time (name, email, phone, etc.)
Declare Tech Stack — List the languages, frameworks, and tools you know
Answer Questions — Respond to the generated technical questions
Finish — The session ends with a summary and next-steps info

Tips

You can type "bye", "exit", or "quit" at any time to end the session
The sidebar shows your screening progress and collected information
If you make a mistake, the assistant will gently ask for correction

Technical Details

Libraries & Tools

Library	Version	Purpose
`streamlit`	≥1.30.0	Frontend UI framework
`groq`	≥0.4.0	Groq API SDK (Llama 3)
`python-dotenv`	≥1.0.0	Environment variable management

Model: Llama 3 via Groq

Why Groq & Llama?

Incredible Speed — Groq's LPU architecture provides instant, real-time responses
Quality — llama-3.3-70b-versatile offers top-tier instruction following and context retention
Efficiency — Uses the smaller llama-3.1-8b-instant model for quick auxiliary tasks (sentiment/language detection) to save API quota
Free tier — Generous free tier for development

Configuration:

Temperature: 0.7 (balanced creativity/consistency for conversations)
Max tokens: 2048 (sufficient for detailed technical questions)
Analytical tasks (sentiment, language): Temperature 0.3 for precision

Design Patterns

State Machine — ConversationManager drives the conversation through ordered phases
Template Method — Phase-specific prompts injected into a consistent prompt structure
Strategy Pattern — Validation rules differ per phase via _extract_and_validate()
Session State — Streamlit's st.session_state for conversation persistence across rerenders

Prompt Design

Philosophy

Prompts are crafted with three principles:

Specificity — Each phase has a tailored prompt that tells the LLM exactly what to do
Constraint — Clear rules prevent the LLM from going off-topic or revealing system details
Context — Phase context is injected alongside user input so the LLM understands the current state

System Prompt

The system prompt defines "Scout's" persona, rules, and behavioral constraints:

Professional yet warm personality
Strict topic adherence (hiring/screening only)
One-field-at-a-time information gathering
Input validation with gentle correction
No code generation or tutoring — assessment only

Phase Prompts

Each conversation phase has a dedicated prompt that:

Tells the LLM what the candidate just provided
Specifies what to validate
Defines what to ask next
Handles edge cases (invalid input, off-topic responses)

Technical Question Generation

The tech question prompt dynamically adjusts based on:

Tech stack — Questions cover the specific technologies listed
Experience level — Difficulty scales with years of experience
Breadth — Questions cover debugging, architecture, best practices, and trade-offs

Fallback Prompt

When input doesn't match the expected phase:

Acknowledges the candidate's message politely
Redirects to the current screening step
Never dismisses or ignores the candidate

Data Privacy & GDPR

Local Storage — All data stored locally in data/candidates/ as JSON files
Anonymization — Email and phone are masked in stored data (original kept for recruiter access)
Right to Erasure — delete_candidate_session(session_id) function available
No External Transmission — Data never leaves the local system (except API calls to Groq for response generation)
Gitignored — The data/candidates/ directory is excluded from version control
Minimal Collection — Only essential screening information is gathered

Bonus Features

Sentiment Analysis

Each candidate message is analyzed for emotional tone
Categories: Positive, Neutral, Negative, Frustrated, Excited, Confused
Displayed as a color-coded badge in the sidebar
Logged in session data for recruiter insight

Multilingual Support

Auto-detects the candidate's language from their messages
Supports 20+ languages including Hindi, Spanish, French, German, and more
When non-English is detected, responses include bilingual translations
Language detection runs on early messages to minimize API calls

Premium UI

Custom dark theme with Inter font
Glassmorphism effects and gradient accents
Smooth message slide-in animations
Progress bar with gradient fill
Responsive chat bubble design
Custom scrollbar styling

Secure Admin Dashboard

Integrated directly into the Streamlit UI via a sidebar toggle
Protected by environment variable credentials (ADMIN_USERNAME and ADMIN_PASSWORD)
Allows recruiters to instantly view saved candidate JSON files and transcripts
Eliminates the need for external database setup during local development and cloud demos

Challenges & Solutions

1. Maintaining Context Across Phases

Challenge: The LLM needed to understand which phase the conversation was in without confusing past context. Solution: Phase-specific context is injected into each prompt call, then stripped from the stored history to keep it clean. The LLM sees [SYSTEM CONTEXT — phase: X] directives that are replaced with the user's actual message in the stored history.

2. Preventing Off-Topic Responses

Challenge: LLMs naturally want to be helpful with any question, even off-topic ones. Solution: The system prompt includes strict rules about topic adherence, and the fallback mechanism provides a polite redirect template that the LLM follows consistently.

3. Input Validation Without Being Annoying

Challenge: Validating email/phone formats while keeping the conversation natural. Solution: Two-layer validation — regex-based extraction in code, plus LLM-level validation prompts that ask for corrections conversationally rather than showing error messages.

4. Exit Keyword False Positives

Challenge: Phrases like "thank you for asking" would trigger exit detection. Solution: Exit detection only triggers on short messages (≤5 words) containing exit keywords, preventing false positives from longer contextual sentences.

5. Technical Question Quality

Challenge: Generating questions that are neither too easy nor too hard. Solution: The prompt includes the candidate's experience level and explicitly requests intermediate-to-advanced questions covering practical aspects (debugging, architecture, trade-offs), not just theoretical knowledge.

Project Structure

talentscout/
├── app.py                      # Streamlit entry point
├── config.py                   # API keys, constants, model configuration
├── requirements.txt            # Python dependencies
├── .env.example                # Environment variable template
├── .gitignore                  # Git ignore rules
├── README.md                   # This file
│
├── core/                       # Core business logic
│   ├── __init__.py
│   ├── conversation.py         # Conversation state machine
│   ├── prompts.py              # All prompt templates
│   ├── llm.py                  # Groq (Llama) API wrapper
│   └── data_store.py           # JSON data persistence
│
├── modules/                    # Bonus feature modules
│   ├── __init__.py
│   ├── sentiment.py            # Sentiment analysis
│   └── language.py             # Language detection & bilingual support
│
├── ui/                         # UI layer
│   ├── __init__.py
│   ├── components.py           # Reusable Streamlit components
│   └── styles.py               # Custom CSS injection
│
├── data/
│   └── candidates/             # Stored session data (gitignored)
│
└── assets/
    └── logo.png                # TalentScout branding

License

This project was built as part of an AI/ML internship assignment. All code is original and open for review.

Name		Name	Last commit message	Last commit date
core		core
modules		modules
ui		ui
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
app.py		app.py
config.py		config.py
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation